host-computer-dev Skill 说明

这份文档分成两部分：

1. 前半部分是白话导读，说明这套 Skill 思路能解决什么问题。
2. 后半部分是原始专业版 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 开发任务分流器"。

⚡ 快速使用： 在 Codex/CodeBuddy 中直接输入 /host-computer-dev 即可调用总入口。一个对话里第一次调用后，AI 会自动在后续对话中应用这套 Skills，不需要每次都重新输入。如果感觉 AI 没按 Skill 规则执行了，再输一次 /host-computer-dev 重新激活。

普通人直接让 AI 写代码，常见问题是：需求没拆清楚、AI 一次改太多、通信和数据库被误伤、Bug 没查清就乱修、改完没有回归测试。

这套 Skill 的思路是：先判断任务类型和风险，再选择对应的处理流程。核心要点：Skills 里已经内置了需求拆解、Bug L1-L5 分级、质量门、回归验收等所有流程，调用 Skill 后 AI 会自动按这套规则执行，你不需要手动填表。

新项目或大功能要先整理零散需求，形成第一版需求方案，再逐步细化；已有项目改动先描述目标或现象，再由 AI 判断需要阅读哪些项目结构、代码、截图或日志。小问题快速修，大功能先拆需求，通信、数据库、线程、真实设备控制这类高风险任务要更谨慎。

2. 总入口说明

对外默认使用 host-computer-dev 这个总入口。

用户不需要一开始记住 00-15 的内部编号。只要描述需求、Bug、通信问题、界面问题、数据库问题、日志问题或文档需求，入口会根据任务类型选择合适的子流程。

如果是新项目，第一步不是让 AI 理解项目结构，因为这时还没有稳定的项目结构。正确顺序是先让 01-requirement-analyst 把零散需求整理成第一版需求方案，再逐步确认缺失信息，最后由 02-system-designer 推导项目结构、技术框架、模块划分和开发顺序。

如果是已有项目，先告诉 AI 修改目标、当前现象、期望效果、Bug 表现或日志线索。AI 应该先判断需要哪些项目结构、相关代码、截图、日志和最近改动，然后再决定是走功能更新、Bug 调查、Bug 修复还是回归验证。

适合的任务包括：

1. WPF / WinForm 上位机开发。
2. 串口 / TCP 通信设计和排查。
3. 协议帧、CRC、粘包半包处理。
4. SQLite / MySQL / CSV 数据保存。
5. UI 卡死、线程、日志、报警、测试流程问题。
6. 技术方案、测试用例、验收报告整理。

2.1 下载 Skill 文件

整套 host-computer-dev 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 编程工具即可生效。

这样做更适合长期使用：

1. 新建项目后不用重复复制 Skill。
2. 后续升级 Skill 时，只需要更新这一个目录。
3. 任意上位机项目都可以调用同一套 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/
└─ ...

但这种方式只是备选，原因是：

1. 放在项目根目录下，不代表 Codex 一定会自动发现。
2. 不同 AI 工具对项目本地 Skill 的识别规则不一样。
3. 每新建一个项目都要复制一次，后续升级也要同步多份。
4. 如果只是放进项目，但没有让 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 的工具，也可以这样用：

1. 先打开 60-host-computer-dev-Skill说明.md。
2. 找到和你任务最接近的模块，例如需求分析、通信、Bug、测试。
3. 把对应说明复制给 ChatGPT。
4. 如果需要更稳定的格式，再补充对应目录下的 TEMPLATE.md 和 EXAMPLE.md。
5. 再粘贴你的需求、代码、日志或协议文档。

示例：

请你按照下面这套上位机开发 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 做分析，不要直接写代码：

1. 需求还没拆清楚。
2. 协议文档不完整。
3. 涉及真实设备控制。
4. 涉及数据库结构变更。
5. 涉及线程、定时器、高频采集。
6. Bug 偶发且没有日志。
7. 不知道会影响哪些文件。

推荐说法：

请先不要写代码。请先分析需求、风险、影响范围和验证步骤。

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	协议、数据库、线程、真实设备、发布交付	需求、方案、测试、回归、验收文档都要完整

简单理解：小修不要搞复杂，大改不要图省事。

⚠️ Skill 路由与分级的关系：L1/L2 小 Bug 直接在对话中修，不要走 09→11→10→12 的完整 Skill 路由——那是给 L4/L5 疑难问题设计的。走完整个调查流程改一个按钮位置，效率极低。只有根因不明、影响跨模块、或涉及真实设备时，才让 Bug 调查 Skill 介入。详见 40-Bug调查与最小修复流程。

5. 写入安全机制

专业版里强调了几个关键安全动作：

1. 修改前先确认目标文件和编码。
2. 修改前创建可恢复快照。
3. 不直接改正式文件，先改工作副本。
4. 改完后读回检查，确认没有乱码、空文件、异常缩短。
5. 如果发现乱码、空文件、读取异常或构建异常，先停下来，不继续覆盖。

这套机制的目的不是增加麻烦，而是避免 AI 把项目文件写坏后无法恢复。

6. 典型调用方式

小修

调用 host-computer-dev，帮我修一下这个 WPF 绑定错误，只做最小修改，不要重构。

功能变更

调用 host-computer-dev，给这个上位机增加参数配置页。请先分析影响范围，再给实现步骤。

复杂 Bug

调用 host-computer-dev，分析这段串口日志为什么偶发丢包。先定位根因，不要直接修代码。

正式交付

调用 host-computer-dev，基于当前项目生成回归测试清单和验收报告。

7. 注意事项

1. 这套 Skill 不承诺一键完成完整商业项目。
2. AI 输出的代码仍然需要人工验证。
3. 真实设备、高危险动作、生产环境必须谨慎测试。
4. 协议、数据库、线程、通信重连这类问题不要只靠一句 Prompt 解决。
5. 如果没有源码、协议文档、日志和测试环境，很多问题只能给排查方向，不能保证直接修好。

---

8. 随包 Skill 目录说明

完整 Skill 文件已放在：

skills/host-computer-dev/

优先阅读：

1. skills/host-computer-dev/README.md
2. skills/host-computer-dev/00-project-orchestrator/SKILL.md
3. 根据任务类型阅读对应子 Skill。

为了提高普通项目开发效率，这份 Skill 说明只保留常见上位机项目需要的流程。普通项目按最小修改、必要备份、修改后验证的原则执行即可。