host-computer-dev Skill 说明
这份文档分成两部分：
- 前半部分是白话导读，说明这套 Skill 思路能解决什么问题。
- 后半部分是原始专业版
host-computer-dev说明，保留给懂 Codex、Claude Code 或 Agent 工作流的人参考。
0. 先看这一段：Skill 不是必装项
如果你是第一次使用这套资料，不用一上来就安装 Skill。
你可以按三种方式使用：
| 使用方式 | 适合谁 | 怎么用 |
|---|---|---|
| 普通 ChatGPT 用法 | 新手、只想先整理需求或问问题 | 直接复制本资料里的 Prompt，把你的需求、日志、截图、协议发给 AI |
| AI 编程工具用法 | 会用 Cursor、Codex、Claude Code 等工具 | 让工具读取本资料，按需求拆解、影响分析、最小修改、回归验收来做 |
| Skill/Agent 用法 | 想长期、稳定地在多个上位机项目复用 | 安装 host-computer-dev，让 AI 自动按任务类型分流 |
简单说：
不会安装 Skill，也能用这套资料。
会安装 Skill，只是让流程更自动、更稳定。第一次建议先看：
81-参考-拿到资料后怎么开始.md
00-先读我-阅读路线.md等你确认自己要长期使用 Codex/Agent，再回来安装 Skill。
1. 白话说明
host-computer-dev 可以理解成一套“上位机 AI 开发任务分流器”。
普通人直接让 AI 写代码，常见问题是：需求没拆清楚、AI 一次改太多、通信和数据库被误伤、Bug 没查清就乱修、改完没有回归测试。
这套 Skill 的思路是：先判断任务类型和风险，再选择对应的处理流程。新项目或大功能要先整理零散需求，形成第一版需求方案，再逐步细化；已有项目改动先描述目标或现象，再由 AI 判断需要阅读哪些项目结构、代码、截图或日志。小问题快速修，大功能先拆需求，通信、数据库、线程、真实设备控制这类高风险任务要更谨慎。
2. 总入口说明
对外默认使用 host-computer-dev 这个总入口。
用户不需要一开始记住 00-15 的内部编号。只要描述需求、Bug、通信问题、界面问题、数据库问题、日志问题或文档需求，入口会根据任务类型选择合适的子流程。
如果是新项目，第一步不是让 AI 理解项目结构，因为这时还没有稳定的项目结构。正确顺序是先让 01-requirement-analyst 把零散需求整理成第一版需求方案，再逐步确认缺失信息，最后由 02-system-designer 推导项目结构、技术框架、模块划分和开发顺序。
如果是已有项目，先告诉 AI 修改目标、当前现象、期望效果、Bug 表现或日志线索。AI 应该先判断需要哪些项目结构、相关代码、截图、日志和最近改动，然后再决定是走功能更新、Bug 调查、Bug 修复还是回归验证。
适合的任务包括：
- WPF / WinForm 上位机开发。
- 串口 / TCP 通信设计和排查。
- 协议帧、CRC、粘包半包处理。
- SQLite / MySQL / CSV 数据保存。
- UI 卡死、线程、日志、报警、测试流程问题。
- 技术方案、测试用例、验收报告整理。
2.1 下载 Skill 文件
整套 host-computer-dev Skill 文件打包在这里：
下载后解压，按下面的说明安装到 Codex/Agent 环境。
2.2 Skill 文件包含什么
本资料包已经附带一套上位机 Skill 文件，位置在：
skills/host-computer-dev/里面包含：
00-project-orchestrator/
01-requirement-analyst/
02-system-designer/
03-ui-designer/
04-protocol-designer/
05-communication-expert/
06-data-storage-designer/
07-code-generator/
08-feature-updater/
09-bug-investigator/
10-bug-fixer/
11-regression-guardian/
12-test-designer/
13-log-analyzer/
14-performance-analyzer/
15-document-generator/
_shared/
README.md这些文件是给支持 Skill/Agent 工作流的 AI 编程工具使用的。如果你只是普通 ChatGPT 用户，也可以直接阅读这些文件，把里面的流程当作提示词参考。
2.2 怎么安装到 Codex/Agent 环境
随包 Skill 的目录是：
skills/host-computer-dev/安装路径说明
目前 AI 编程工具（Codex CLI、Claude Code、Cursor、Gemini CLI 等）共同遵循一套 Skill 目录标准。推荐使用 .agents/skills/ 作为跨工具通用的用户级 Skill 目录。
| 安装范围 | 路径 | 说明 |
|---|---|---|
| 用户级（推荐） | C:\Users\你的用户名\.agents\skills\ | Codex CLI 默认目录，跨工具通用，所有项目都能调用 |
| 用户级（备选） | C:\Users\你的用户名\.codex\skills\ | Codex 专用目录，如 .agents 不生效时可尝试 |
| 项目级 | 你的项目\.agents\skills\ | 仅当前项目可用，可提交 Git 团队共享 |
注意：
你的用户名需要换成你自己电脑的实际用户名（比如Admin、Administrator或者你的个人账号名）。不确定的话，打开文件资源管理器，在地址栏输入%USERPROFILE%回车，就能看到你的用户目录。
方式一：作为全局 Skill 使用（推荐）
把 skills/host-computer-dev/ 整个目录复制到 C:\Users\你的用户名\.agents\skills\ 下。
复制完成后的目录结构：
C:\Users\你的用户名\.agents\skills\host-computer-dev\
├─ README.md
├─ 00-project-orchestrator\SKILL.md
├─ 01-requirement-analyst\SKILL.md
├─ 02-system-designer\SKILL.md
├─ ...
├─ 15-document-generator\SKILL.md
└─ _shared\然后重新打开或刷新 AI 编程工具即可生效。
这样做更适合长期使用：
- 新建项目后不用重复复制 Skill。
- 后续升级 Skill 时，只需要更新这一个目录。
- 任意上位机项目都可以调用同一套
host-computer-dev。
如果你不确定用户名，或者 .agents 目录还不存在，可以直接让 AI 工具帮你做：
请扫描当前资料包里的 skills/host-computer-dev 目录。
请把它安装到我的全局 Skill 目录。
先帮我确认当前工具使用的 Skill 目录是 .agents\skills 还是 .codex\skills。
再把这个 Skill 复制过去，并检查是否安装完整。方式二：作为项目本地资料使用（备选）
也可以把整个 skills/host-computer-dev/ 目录复制到某一个上位机项目目录里。
最终结构类似：
你的上位机项目/
├─ skills/
│ └─ host-computer-dev/
│ ├─ 00-project-orchestrator/
│ ├─ 01-requirement-analyst/
│ ├─ 02-system-designer/
│ ├─ ...
│ ├─ 15-document-generator/
│ └─ _shared/
├─ src/
└─ ...但这种方式只是备选，原因是：
- 放在项目根目录下，不代表 Codex 一定会自动发现。
- 不同 AI 工具对项目本地 Skill 的识别规则不一样。
- 每新建一个项目都要复制一次，后续升级也要同步多份。
- 如果只是放进项目，但没有让 AI 明确读取，它可能完全不起作用。
如果使用项目本地方式，建议明确告诉 AI：
请读取当前项目中的 skills/host-computer-dev/README.md 和各子目录 SKILL.md。
后续处理本项目时，请把它们作为上位机开发规则执行。每个子 Skill 目录建议同时保留：
SKILL.md # 角色、流程、禁止事项
TEMPLATE.md # 标准输入输出和质量标准
EXAMPLE.md # 最小示例如果你的工具不支持自动识别 Skill，也可以直接阅读对应 SKILL.md，把里面的工作流程复制到 ChatGPT 或其他 AI 工具里使用。输出不稳定时，再补充同目录下的 TEMPLATE.md 和 EXAMPLE.md。
如果你使用的不是 Codex，也可以让当前 AI 工具扫描 skills/host-computer-dev/，再把这套流程转换成它自己的项目规则、快捷指令或专家角色。具体怎么把通用 Skill 改成自己的行业 Skill，可以看 61-Skill成长与二次定制.md。
2.3 普通 ChatGPT 用户怎么用
如果你不用 Codex、Claude Code 或其他支持 Skill 的工具，也可以这样用：
- 先打开
60-host-computer-dev-Skill说明.md。 - 找到和你任务最接近的模块，例如需求分析、通信、Bug、测试。
- 把对应说明复制给 ChatGPT。
- 如果需要更稳定的格式，再补充对应目录下的
TEMPLATE.md和EXAMPLE.md。 - 再粘贴你的需求、代码、日志或协议文档。
示例：
请你按照下面这套上位机开发 Skill 的思路工作。
当前任务类型：串口/TCP 通信问题排查。
要求：先分析，不要直接写代码。
下面是 Skill 说明：
【粘贴 05-communication-expert 或本文件相关说明】
下面是我的问题：
【粘贴日志、协议、代码和现象】2.4 推荐调用方式
新项目需求拆解
调用 host-computer-dev，帮我分析这个上位机项目需求。
请先不要写代码，也不要直接设计项目结构。
第一步请先把下面零散需求整理成第一版需求方案。
第二步请列出还需要我确认的问题。
第三步再根据确认后的需求方案，推导技术路线、项目结构、模块边界、开发顺序、风险点和验收标准。
需求如下：
【粘贴需求拆解表】WPF 页面设计
调用 host-computer-dev，帮我设计这个 WPF 上位机页面。
我先用业务语言描述页面目标，不确定具体控件、绑定字段和 Command 名称。
请你先根据页面目标，推导页面区域、控件建议、状态字段、按钮命令、ViewModel 职责、Service 依赖和验收点，不要直接写完整代码。
页面目标：
使用人员：
需要显示的信息：
需要执行的操作：
异常提示要求：WPF 页面修改
调用 host-computer-dev，帮我修改一个已有 WPF 上位机页面。
请先不要写代码，也不要重写整个页面。
我暂时不确定具体要改哪个 XAML、ViewModel 或 Command，请你先根据目标判断可能影响哪些页面区域、状态字段、按钮命令和服务。
修改目标：
当前现象：
期望效果：
不希望影响：
如果信息不够，请告诉我需要补充哪些截图、项目结构、代码文件或日志。
请先输出影响范围、最小修改思路、风险点和回归验证清单。串口/TCP 通信设计
调用 host-computer-dev，帮我设计通信模块。
通信方式：
协议格式：
示例报文：
CRC 规则：
粘包半包要求：
重连/心跳要求：
请先输出通信状态机、接收缓存、协议解析、异常处理和测试清单。
要求接收和解析分开：
1. 接收线程只负责读取原始字节并写入缓存或队列。
2. 解析线程独立处理粘包、半包、校验和协议解析。
3. 解析后的业务数据再根据项目需要分发到界面显示、数据保存、报警或测试流程。Bug 调查
调用 host-computer-dev，帮我调查这个 Bug。
请先只定位根因，不要修改代码。
问题现象：
复现步骤：
日志：
相关代码或截图：
【如果不知道相关文件，先让 AI 判断需要补充哪些材料】
最近改动：最小修复
调用 host-computer-dev，根因已经确认，请给最小修复方案。
要求：
1. 不重构无关代码。
2. 不扩大修改范围。
3. 修改前说明影响范围。
4. 修改后给回归测试清单。2.5 什么情况下不要直接让 Skill 写代码
以下情况先让 Skill 做分析，不要直接写代码：
- 需求还没拆清楚。
- 协议文档不完整。
- 涉及真实设备控制。
- 涉及数据库结构变更。
- 涉及线程、定时器、高频采集。
- Bug 偶发且没有日志。
- 不知道会影响哪些文件。
推荐说法：
请先不要写代码。请先分析需求、风险、影响范围和验证步骤。3. 子 Skill 清单
| 编号 | 模块 | 主要职责 |
|---|---|---|
| 00 | 项目编排 | 判断任务阶段、风险和路由 |
| 01 | 需求分析 | 把口头需求拆成结构化需求 |
| 02 | 系统设计 | 设计模块、数据流、线程模型、状态机 |
| 03 | UI 设计 | WPF / WinForms 页面和交互设计 |
| 04 | 协议设计 | 帧格式、CRC、组包拆包、状态机 |
| 05 | 通信专家 | 串口 / TCP 连接、重连、超时、丢包排查 |
| 06 | 数据存储 | SQLite / MySQL 表结构、索引、迁移 |
| 07 | 代码生成 | 在需求明确后生成实现代码 |
| 08 | 功能更新 | 已有项目的增量功能修改 |
| 09 | Bug 调查 | 先定位根因，不急着修 |
| 10 | Bug 修复 | 根因明确后的最小修复 |
| 11 | 回归守护 | 修改后评估影响范围和回归点 |
| 12 | 测试设计 | 测试计划、测试用例、覆盖矩阵 |
| 13 | 日志分析 | 根据日志和时间线定位问题 |
| 14 | 性能分析 | UI 卡顿、CPU、内存、通信延迟分析 |
| 15 | 文档生成 | 验收报告、技术方案、总结文档 |
4. 风险分流机制
这套流程不是所有问题都走重流程，而是按风险分流。
| 客户理解 | 专业版叫法 | 适合任务 | 处理方式 |
|---|---|---|---|
| L1 直接小改 | Direct Patch / Micro Patch | 拼写、按钮位置、简单样式、简单编译错误 | 直接最小修改，做最便宜验证 |
| L2 快速修复 | Quick Fix / Quick Patch | 根因基本明确的小 Bug、局部异常、少量文件修改 | 快速修复，不走完整调查 |
| L3 普通变更 | Standard Change | 普通功能变更、已有流程增量修改 | 先做影响分析，再实现和聚焦回归 |
| L4 疑难问题 | Investigation | 通信数据不对、协议解析异常、偶发问题、现场才复现 | 先调查根因和证据链，再修复 |
| L5 高风险/正式交付 | High Risk / Formal | 协议、数据库、线程、真实设备、发布交付 | 需求、方案、测试、回归、验收文档都要完整 |
简单理解：小修不要搞复杂，大改不要图省事。
5. 写入安全机制
专业版里强调了几个关键安全动作：
- 修改前先确认目标文件和编码。
- 修改前创建可恢复快照。
- 不直接改正式文件，先改工作副本。
- 改完后读回检查，确认没有乱码、空文件、异常缩短。
- 如果发现乱码、空文件、读取异常或构建异常，先停下来，不继续覆盖。
这套机制的目的不是增加麻烦，而是避免 AI 把项目文件写坏后无法恢复。
6. 典型调用方式
小修
调用 host-computer-dev，帮我修一下这个 WPF 绑定错误，只做最小修改，不要重构。功能变更
调用 host-computer-dev，给这个上位机增加参数配置页。请先分析影响范围，再给实现步骤。复杂 Bug
调用 host-computer-dev，分析这段串口日志为什么偶发丢包。先定位根因，不要直接修代码。正式交付
调用 host-computer-dev，基于当前项目生成回归测试清单和验收报告。7. 注意事项
- 这套 Skill 不承诺一键完成完整商业项目。
- AI 输出的代码仍然需要人工验证。
- 真实设备、高危险动作、生产环境必须谨慎测试。
- 协议、数据库、线程、通信重连这类问题不要只靠一句 Prompt 解决。
- 如果没有源码、协议文档、日志和测试环境，很多问题只能给排查方向，不能保证直接修好。
8. 随包 Skill 目录说明
完整 Skill 文件已放在：
skills/host-computer-dev/优先阅读：
skills/host-computer-dev/README.mdskills/host-computer-dev/00-project-orchestrator/SKILL.md- 根据任务类型阅读对应子 Skill。
为了提高普通项目开发效率，这份 Skill 说明只保留常见上位机项目需要的流程。普通项目按最小修改、必要备份、修改后验证的原则执行即可。