# 沧溟 - 游刃

**Repository Path**: fangyu_fy/youren

## Basic Information

- **Project Name**: 沧溟 - 游刃
- **Description**: 游刃是面向 AI Agent 生态的 自定义 Skill 文档知识库，为智能体提供精准、结构化、可被机器理解的技能描述规范。它不存储可执行代码，不包含运行时逻辑，仅作为一系列离散、自包含、语义明确的 Skill 定义文档集合 而存在——让 Agent 在面对串口调试、协议解析、设备交互等具体任务时，得以“知其刃之所向、明其锋之所限”，在正确的时机以正确的方式调用正确的能力。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-28
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 游刃（Youren）

游刃是面向 AI Agent 生态的自定义 Skill 文档知识库，为智能体提供精准、结构化、可被机器理解的技能描述规范。

它不存储业务可执行代码，不包含运行时逻辑，仅作为一系列离散、自包含、语义明确的 Skill 定义文档集合而存在——技能描述的重心落在「怎样把代码写好」这类工程问题上，包括框架的基本原则、插件模式如何应用、设计模式如何应用、逻辑如何分层、契约如何表达、评审依据什么，注释与文档规范等；同时也包括串口调试、协议解析、设备交互这类具体任务的做法，让 Agent 得以「知其刃之所向、明其锋之所限」，在正确的时机以正确的方式调用正确的能力。

## 一、定位与边界

游刃是**技能文档的真源**：一个技能在任何地方出现多个副本时，以游刃里的这一份为准，其余副本都是从这里分发出去的下游拷贝。确立这条的唯一理由是此前吃过的亏——同一份技能散落成 27 个 profile 副本与 8 处仓库副本之后，各自漂移成了互不相容的三个版本，而每个 Agent 都只是照着眼前那份执行，谁也没有错，错在没有真源。

它收录什么，不收录什么，边界如下：

- **收录**：跨项目复用的 Agent 技能文档，即「在什么时机、按什么规范、做什么事」的可复用描述，以及与技能配套的、仅用于文档自身校验或转换的小工具；包括框架的基本原则、插件模式如何应用、设计模式如何应用、逻辑如何分层、契约如何表达、评审依据什么，以及注释与文档规范等「怎样把代码写好」的工程技能，同时也包括串口调试、协议解析、设备交互这类具体任务的做法。
- **不收**：任何业务运行时逻辑、与具体项目耦合的实现细节、密钥与凭据（包括个人访问令牌、AccessKey、密码、`.env`、`auth.json`）、以及只能被单个项目理解的私有约定。
- **小工具的取舍口径**：允许随技能附带校验/转换脚本乃至编译好的工具（例如注释规范的段落行数自检器），因为这类小工具服务于文档自身的质量，不构成任何产品的运行时；禁止携带的是「技能一被加载就会执行业务逻辑」的那种代码。
- **外部维护的技能**：由上游作者维护、本仓只登记坐标不收录正文的技能，登记在 `docs/spec/external-skills.md`。之所以不收录正文，是因为这类技能的真源在上游：正文一旦拷进来就变成需要手工合并的 fork，上游的修复要在本仓重演一遍，本仓的版本纪律又与上游的版本号各说一套。

## 二、目录结构

```
youren/
├── README.md                       # 本文件：定位、边界、索引、消费与维护约定
├── AGENTS.md                       # 面向 Agent 的路由表：技能名 → 加载时机 → 路径
├── LICENSE                         # MIT
├── docs/
│   ├── README.md                   # 文档体系索引
│   └── spec/
│       ├── skill-doc-spec.md       # 游刃技能文档规范（本仓自己的第一份居民）
│       ├── workgroup-binding.md    # 工作群绑定表规范（跨工作群技能如何落到具体取值）
│       └── external-skills.md       # 外部来源技能登记表（上游坐标、钉住的提交、核对记录）
├── tools/
│   ├── sync-skills.cs              # 本仓 → 目标技能目录的单向同步器（含 --self-test）
│   └── fetch-external.cs           # 上游 → 目标技能目录的外部分发与核对（含 --self-test）
└── skills/
    ├── csharp-doc-style/           # 技能一律占一个同名目录
    │   ├── SKILL.md
    │   └── scripts/scan-remarks.cs
    ├── morning-review/             # 开工回顾：读上次小结、体检状态、输出今日议程
    │   └── SKILL.md
    ├── eod-wrapup/                 # 收工收尾：写小结落盘、提交备份、更新计划与决策
    │   └── SKILL.md
    ├── docs-scaffold/              # docs 体系初始化、补全与升级（八类目录 + 脚本带 --audit 体检）
    │   ├── SKILL.md
    │   ├── scripts/init-docs.cs
    │   └── templates/              # 规则 README、七个过程类示例与三个交付类自述（占位符化）
    ├── tdd-and-unit-testing/       # TDD 纪律与 .NET 单元测试写法（红绿重构 + xUnit/FluentAssertions/Moq）
    │   └── SKILL.md
    └── agent-project-rollout/      # 项目接入与技能同步（新建接入 / 已有项目体检两场景 + 分发工具契约）
        └── SKILL.md
```

`skills/<名称>/SKILL.md` 这一层布局不是随意定的：它与 Hermes、以及多个同源 harness 的技能根约定一致，因此本仓可以**直接被当作技能根加载**，无需为共享而额外发明一套格式或做一次转换。

## 三、技能索引

| 技能 | 加载时机 | 版本 | 路径 |
|---|---|---|---|
| csharp-doc-style | 编写或评审 C# 注释、XML Doc、技术文档（ADR/Plan/Design/规范）时 | 2.0.0 | `skills/csharp-doc-style/` |
| morning-review | 用户以开工语打招呼（上班、开工、回顾、morning）时 | 1.0.0 | `skills/morning-review/` |
| eod-wrapup | 用户说下班、做总结、收工、wrap up 时 | 1.0.0 | `skills/eod-wrapup/` |
| docs-scaffold | 新建项目初始化、或已有项目体检补全与升级 docs 目录与规则时 | 4.0.0 | `skills/docs-scaffold/` |
| tdd-and-unit-testing | 写生产代码或改单元测试（TDD、测试先行、加测试、补测试）时 | 1.2.0 | `skills/tdd-and-unit-testing/` |
| agent-project-rollout | 新建项目接入 agent、或已有项目做技能同步与体检时 | 1.2.0 | `skills/agent-project-rollout/` |

## 四、如何被消费

**零号动作：第一次接入（本机 → 项目）。** 同事拿到本仓后先走完这五步，走完即具备「真源唯一」的本机形态，每步的判据与踩坑见 `skills/agent-project-rollout/SKILL.md`：

1. **克隆到本机原生文件系统**：`git clone <本仓地址> ~/.hermes/youren`；不要直接指向挂载盘上的工作副本，理由见技能第 6 节。
2. **让每个 profile 指向克隆**：`hermes config set skills.external_dirs '["~/.hermes/youren/skills"]'`，指定 profile 时加 `-p <profile>`；配置一律这样写，不手改 `config.yaml`。
3. **清掉本地同名副本**：删除 `~/.hermes/skills/<技能名>` 与 `~/.hermes/profiles/<profile>/skills/<技能名>`，它们会静默压住克隆版本。
4. **铺开项目侧副本**：按 `skills/agent-project-rollout/SKILL.md` 的场景一（新建接入）或场景二（已有项目体检与同步）执行——定技能根、登记目标清单、同步器落盘、写根路由表、各仓独立提交。
5. **核验并定口径**：让加载器回答（各 profile 能列出本仓技能、本地同名副本为 0）；工作目录会落在项目仓库的 profile，按技能第 6 节选定「项目副本要不要生效」的口径，默认不 trust 项目仓库。

四条使用路径，按「谁需要这份内容」区分：

1. **Agent 直接加载**：把仓库克隆到本机原生文件系统上，再让工具把它作为技能根（Hermes 的写法是在 profile 配置的 `skills.external_dirs` 里加一条，指向 `<克隆>/skills`），或把 `skills/` 下某个目录复制到本地技能目录（例如 Hermes 的 `~/.hermes/skills/`）之后，Agent 会在命中触发词时自动加载；克隆方式的更新只需 `git pull`，不再需要复制。
2. **本机部署**：`tools/sync-skills.cs` 把 `skills/` 下的技能同步到一个或多个目标技能目录（`--dry-run` 预览、`--skills` 限定、sha256 校验，重复执行不产生差异）；机器专属的目标清单不进仓库，用 `--targets-file <文件>` 传入。
3. **随项目分发**：项目仓库里的副本（`.agents/skills/`、`.ai/skills/`、`.dsh/skills/` 三种约定并存）是给该项目团队与其它工具读取的下游拷贝，由同步脚本覆盖，**不要在副本上直接修改**——改在那里等于把真源又弄丢一次。
4. **外部分发**：由外部维护、只在 `docs/spec/external-skills.md` 登记坐标的技能，正文不进本仓，用 `tools/fetch-external.cs` 从上游取出钉住的提交后分发到各目标；同一工具的 `--verify` 核对副本与那个提交是否逐字节一致（`--install` 默认只预演，落盘要显式加 `--apply`）。

## 五、维护约定

- **只在游刃里改**：任何技能内容的修订都先落在本仓，再同步到部署点与各项目副本；副本上出现的、与本仓不一致的内容一律以本仓为准。
- **两张索引表随版本同步**：改任何技能的正文或版本时，同一轮里把 §三 的技能索引表与 `AGENTS.md` 的按需技能表一起改到位；索引表漏一次，读者就按旧版本办事（`agent-project-rollout` 的 1.1.0 就漏过一次，本次一并修回）。
- **版本语义**：`version` 字段用语义化版本，正文或自检清单的行为发生变化升 minor，仅补字段、改措辞、纠错别字升 patch，不向后兼容的改变升 major；`description` 与触发条件属于行为的一部分，改动同样要升版本。
- **提交信息**：中文，`type: 摘要` 形式（`docs:`/`feat:`/`fix:`/`chore:`），一次提交只做一件事。
- **工具语言**：仓内的自检与同步小工具一律用 C# 写（.NET 10 单文件应用，首行 shebang 可直接执行，Windows 下用 `dotnet run <工具>.cs -- 参数`），因为它们由 C# 团队维护，出问题要能自己读懂；每个工具都带 `--self-test`，改动后先跑自检再提交。注意 dotnet 驱动层会截走 `--help`/`-h` 与 `--project`，工具因此另设 `help`/`-?` 与 `--proj` 别名。
- **安全红线**：入库前自查无密钥，命令见 `docs/spec/skill-doc-spec.md` 的自查一节。
- **规范先行**：新增技能必须符合 `docs/spec/skill-doc-spec.md`；规范本身也是本仓的文档，新增或修订规范同样走本仓的提交流程。
- **两类技能两套路**：自研技能在 `skills/` 下、由 `tools/sync-skills.cs` 单向同步；外部技能只在 `docs/spec/external-skills.md` 登记、由 `tools/fetch-external.cs` 分发。不得把外部技能的正文拷进 `skills/`，那等于把上游的真源在本仓又造了一份需要手工合并的副本。
- **行尾一律 LF**：本仓与全部分发出去的副本（含外部技能副本）统一 LF，避免同一内容因行尾不同而在核对时出现假差异；外部技能副本的行尾由 `tools/fetch-external.cs` 统一，不要手工改副本。
- **部署时序**：维护期只动本仓，不动部署点与各仓副本；等本仓这一轮的维护全部做完，再一次性向各工作群分发并各自提交，避免同一份内容反复落盘、每改一次就在各处留一次提交。外部技能同此：登记表里的坐标先定好，铺开时机与自研技能一致。