# skill-work

**Repository Path**: cloud-breeze/skill-work

## Basic Information

- **Project Name**: skill-work
- **Description**: 这是一个适合你工作使用的skill
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-11
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# skill-work 使用说明

> 这是一套**通用工作知识框架**。给 AI 用的完整规则在 `SKILL.md`，本文件只讲**你怎么用**。

## 组织架构

![skill-work 组织架构](docs/architecture.svg)

三层结构自上而下：**入口层**（SKILL.md，102 行，只放规则和路由）→ **注册表**（_registry.md，一切路径唯一入口）→ **三大模块**（协议 / 脚本 / 领域包）。五自我闭环负责自我治理，G1-G8 机器门禁负责把规则变成可拦截的检查，三级同步保证多环境不漂移。

## 快速开始（你要准备什么）

### ✅ 必装（缺一不可）

- [ ] **Python 3.10+**（用于跑 scripts/*.py 自检/同步/检查脚本）
  - 验证：`python --version` 应 ≥ 3.10
  - Windows 推荐用本机 `python` 即可；WorkBuddy 走的是 `python3` 别名
- [ ] **Git**（用于 `code-commit-log` 板块从真实源取数）
  - 验证：`git --version`
  - 仅当项目用 git 管代码时必装；不用 git 的项目这个板块会空
- [ ] **PowerShell 5.1+**（Windows）/ **bash 4+**（macOS / Linux）
  - 用于执行 `one-click-init.py --plan` 之前的预检

### ✅ 必建（结构）

```
桌面/
└── dj-work-skills/
    └── skill-work/         ← 这个 skill 的根（最终源）
        ├── SKILL.md
        ├── README.md       ← 本文件
        ├── references/
        │   ├── standards.md
        │   ├── _registry.md
        │   ├── daily-changelog.md
        │   ├── code-commit-log.md
        │   ├── protocol/
        │   └── domains/
        └── scripts/
            ├── check-drift.py
            ├── check-standards.py   ← ⭐ 必装
            ├── fix-desktop-junction.py
            ├── one-click-init.py
            └── sync-to-desktop.py
```

**首次同步**（让当前 AI 工具的用户级目录拿到副本）：

```bash
# 1. 桌面 SSOT 已在 → 跑同步
python scripts/one-click-init.py --plan
# 看输出，确认无破坏性项
python scripts/one-click-init.py --apply --i-agree

# 2. 验证（应全 PASS）
python scripts/check-standards.py references/standards.md
```

### ✅ 必配（领域包）

框架不绑定任何技术。**有合适的领域包就激活一个**（板块 2–4 有实质内容）；暂时没有时用**通用模型**兜底——板块 2–4 建引导骨架（值留空，见 `generic-skeleton.md`），规范、日志、产出记录照常可用。

- **激活领域包由主人显式选择**（见 `_registry.md §2`；候选 = 各 `domains/` 包 + 通用模型，首次初始化默认通用，AI 禁止按工作内容自动激活）
- 没有合适的领域包？→ 走「新建领域包」流程（`SKILL.md §11 NEW-DOMAIN`，5 项询问）

### 🟡 可选（强烈推荐）

- [ ] **UTF-8 终端**（避免 Windows 终端乱码）：
  - PowerShell：`[Console]::OutputEncoding = [System.Text.Encoding]::UTF8`
  - 永久化：加进 `$PROFILE`
- [ ] **Codex / Claude / WorkBuddy 任一客户端**——本 skill 是给 AI 用的，必须在能加载 skill 的工具里跑
- [ ] **git 配好 user.name / user.email**——`code-commit-log` 板块会用

### ❌ 不需要

- ❌ 数据库客户端（迁移 SOP 是参考，具体连库时再装）
- ❌ 任何特定 IDE（规则与编辑器无关）
- ❌ 网络（除非要同步多台机器）

---

### ⚠️ Windows 路径小坑（Git Bash 用户必看）

- Git Bash 下 `/e/foo` 调 Python 会变成相对路径 `\e\foo`（"路径不存在"）
- **正确写法**：用 Windows 风格 `E:/foo` 或 `E:\foo`
- 示例：`python scripts/check-standards.py E:/myproject --strict`
- **错误示例**：`python scripts/check-standards.py /e/myproject --strict`（Python 找不到）

---

## 验证三步（确认装好）

```bash
# 1. 脚本能跑
python scripts/check-standards.py README.md
# 期望：[PASS] 或仅提示 Markdown 不属于代码类

# 2. 桌面 SSOT 与工具用户级一致
python scripts/check-drift.py
# 期望：仅报 protocol/ 路径差异

# 3. 让 AI 加载 skill（手动验证）
#    在 Codex / Claude / WorkBuddy 里说：「dj」或「加载 skill-work」
#    期望：AI 输出 Step 5 模板（带"已读 standards.md"证据行）
```

**三步全过 → 装好，可以开始用了。**

---

## 这是什么

一个约束 AI「怎么组织知识、怎么干活、怎么沉淀」的框架。它**不绑定任何具体技术**——框架只定义 6 个空槽位，具体内容由**领域包**填充。

当前激活领域包见 `_registry.md §2`（**由主人显式选择**）。你换方向（比如做 AI 应用开发）时，**框架一个字不用改**，只需新建一个领域包并切换激活。

## 核心设计：内核 + 领域包

| | 内核（SKILL.md） | 领域包（domains/） |
|---|---|---|
| 管什么 | 知识怎么分层、路由、同步 | 具体规范和事实 |
| 换领域 | **不变** | **整个换掉**（除 `standards` 补充条款） |
| 举例 | 「产出前必须先读基线 + 领域补充」 | standards 补充条款是什么内容 |

好处：框架可以分发给任何岗位的同事；他只要配一个自己的领域包就能用。

## 五自我闭环 + 机器门禁（自我治理）

框架不只是被动遵守规则，而是带一套**自治理闭环**——每个自我都有机器抓手，不依赖 AI 自觉：

| 五自我 | 机器抓手 | 触发 |
|---|---|---|
| ① 自我发现 | `skill-audit.py`（A1-A8 审计 + `--clean` C1-C4 清理清单） | 每周 / 出事即记 |
| ② 自我思考 | 真问题归因 → `improvement-backlog.md` | 发现必留痕 |
| ③ 自我优化 | `record-issue.py` + S/M/L 分级落地 | backlog 择期处理 |
| ④ 自我检查 | `check-skill-health.py` **G1-G8** + `run-regression.py` 回归 | 启动 / 改动后必跑 |
| ⑤ 自我约束 | **G7 膨胀预算门禁**（SKILL.md ≤112 行 / 硬规则 = 6 / 协议 ≤15 / references ≤基线 +10%，领域包目录除外） | 新增规则前拦截，**一进一出** |

**机器门禁一览**：G1 引用一致 ｜ G2 计数一致 ｜ G3 策略机器化 ｜ G4 冗余 ｜ G5 路由全覆盖 ｜ G6 领域隔离 ｜ G7 膨胀预算 ｜ G8 测试对账（场景总表〔机判〕标记 ↔ 回归脚本双向锁死）

**测试体系**：回归场景数与机判/半自动/人工分布以 `references/protocol/testing/skill-test-scenarios.md` 场景表实计为准，每次回归自动向 `daily-changelog.md` 留痕机判覆盖率趋势。**事故→测试转化**——任何真实故障修复后必须落一个 T 场景，**修完不留测试视为未修复**，测试集随事故自动生长。

## 六个基础板块

| # | 板块 ID | 记什么 | 谁提供 | **项目里怎么放** |
|---|---|---|---|---|
| 1 | `standards` | 规范与约束（命名、格式、禁用写法） | **基线**=框架自带；**补充**=领域包 | **全局唯一**——基线在内核、补充跟领域包走，项目里**完全不建**，只读引用 |
| 2 | `tooling` | 工具与技术（怎么调用、踩过什么坑） | 领域包 | 同步一份只读参考 |
| 3 | `context` | 领域事实（背景、上下游、关键决策）**+ 项目附加约定** | 领域包 | 项目专属 |
| 4 | `playbook` | 流程 SOP（重复性操作的标准步骤） | 领域包 | 项目专属 |
| 5 | `activity` | 工作日志（今天做了什么，AI 自动写） | 框架自带 | 项目专属 |
| 6 | `deliverables` | 产出记录（从 git 等真实源取数） | 框架自带 | 项目专属 |

`standards` 拆成**基线 + 领域补充**两层：基线永远在内核，跨项目跨领域都是同一份；领域补充跟领域包走（换领域时换）。**两个都不进项目级**。

> **规范为什么不在项目里放一份**：规范的意义就是**所有项目都遵守**。项目里一旦有第二份，就变成"这个项目用自己那套"，规范随即失效。
> 项目有额外要求怎么办？记进 `context` 标为「本项目附加约定」，**只能比基线更严，不能更松**；冲突时以基线为准。

## 快速开始

1. 把 `skill-work/` 整个目录放到工具的用户级 skill 目录：
   - Codex CLI：`~/.codex/skills/skill-work/`
   - Claude Code：`~/.claude/skills/skill-work/`
   - WorkBuddy：`~/.workbuddy/skills/skill-work/`
2. 在工具里执行 `/skill skill-work`
3. 发一句触发词（`dj` / `你好` / `hello` / `dj666` / `1`）→ AI 自动跑初始化，建齐目录并汇报状态

**注意**：skill 名取的是**目录名**（`skill-work`），不是文件里的 `name` 字段。要改名直接改目录名。

## 日常怎么用

| 你说 | AI 做什么 |
|---|---|
| `dj` / `你好` | 跑初始化：建桌面基准、校验板块、报状态 |
| 「补充 XX 方法」 | **强制三段**：① 读 standards 基线+领域补充 ② 逐条对照+末尾打印自查表 ③ 跑 `check-standards.py` 修到 PASS → 产出 → 回写板块 → 记日志 |
| 「生成提交记录」 | 从 git 读改动 → 生成 commit message **给你确认**，**不会自动提交** |
| 「补充 XX 到 skill」 | 判断属于哪个板块 → 去重后写入 |
| 「看 token 用量」 | `python scripts/session-token-report.py --all-projects --gate`（默认阈值 800k），FAIL = 有超阈值会话 → 触发会话交接 |
| 「会话交接 / 续接」 | 按 `session-handoff.md` 写 7 段交接摘要存项目 chatLog，新会话说「继续 <文件>」读文件续接 |
| 「今天改了什么」 | 从 git 取当天提交，汇总给你 |
| 「换领域 / 新方向」 | 问你 5 项 → 建新领域包 → 切注册表（SKILL.md 不动） |

## 目录结构

```
skill-work/
├── SKILL.md                        # 通用内核：规则 + 路由（不含任何领域值）
├── README.md                       # 本文件，给人看
└── references/
    ├── standards.md                  # 板块1 基线（框架自带，全局唯一）
    ├── generic-skeleton.md           # 通用模型基础骨架标准（未激活领域包时项目 chatLog 引导模板）
    ├── _registry.md                  # 板块注册表 ⭐ 一切路径的入口
    ├── daily-changelog.md            # 板块5 activity（框架自带）
    ├── code-commit-log.md            # 板块6 deliverables（框架自带）
    ├── improvement-backlog.md        # 反馈累积池（§11 配套，backlog）
    ├── CHANGELOG.md                  # skill 自身演进日志（§11 配套）
    ├── business/                     # 项目专属业务文件（不外发）
    ├── commit/YYYY-MM-DD.md          # 当天产出详情
    ├── protocol/                     # 14 个内核协议（初始化全流程 = initialization-flow.md；知识闭环 = knowledge-lifecycle.md；回归测试 = skill-test-scenarios.md；五自我 = growth-protocol.md §4.5）
    └── domains/                      # 领域包（可并存多个，同时激活一个）
        └── <domain-id>/              # 领域包目录名 = 领域包 id（当前激活见 _registry.md §2）
            ├── DOMAIN.md             # 领域清单：已确定什么、必须问什么
            ├── standards-addendum.md # 板块1 领域补充（只能补充/收紧）
            ├── tech-stack-usage.md   # 板块2 tooling
            ├── business-summary.md   # 板块3 context
            └── data-migration.md     # 板块4 playbook
scripts/                               # 可执行脚本（强制抓手，AI 必须调用）
├── check-skill-health.py             # ⭐ skill 健康自检（启动必跑，FAIL 先修）
├── skill-audit.py                    # 五自我 发现/思考/清洁（A1-A8 自审候选 + --clean C1-C4 清理清单）
├── check-drift.py                    # 三级同步差异检测
├── fix-desktop-junction.py           # 桌面 SSOT 修复
├── one-click-init.py                 # 一键初始化
├── sync-to-desktop.py                # L1 → L0 反向同步（需授权）
├── run-regression.py                 # 回归测试（发版前必跑）
├── record-issue.py                   # 失败/自检自动记 backlog [AI 发现]
├── show-standards.py                 # 展示规范（基线+领域补充）
├── session-token-report.py           # 会话 token 用量报告（--gate 闸门：超 800k 退出码 1，触发会话交接）
└── check-standards.py                # ⭐ 基线自动检查（覆盖范围以脚本实计为准）+ 末条提示项（生成代码后必跑）
```

## 三级同步，方向别搞反

| 级别 | 位置 |
|---|---|
| **L0 桌面 SSOT** | `<桌面>\dj-work-skills\skill-work\`（最终基准，备份就复制整个目录） |
| **L1 工具用户级** | `~/.codex` / `~/.claude` / `~/.workbuddy/skills/skill-work/` |
| **L2 项目级** | `<项目>/.codex` 或 `/.claude/chatLog/`（目录按板块 ID 命名，**5 个**：无 `standards`） |

- **分发**（换工具 / 新建项目）：L0 → L1 → L2（`standards` 基线 + 补充都不复制进项目，只读引用）
- **沉淀**（产生新知识）：L2 → L1 → L0；**项目专属内容不上传**，只有通用规则上浮，进 L0 需你授权
- **改规范**：只能改 L1（用户级），改完影响所有项目，所以 AI 会先问你；项目级没有规范的修改权（连项目附加约定的"放宽"都禁止）

## 三个提醒

- **待确认变量 AI 会主动问**：当前领域包里「数据库类型」是待确认项——AI 每次写 SQL 前会问你用的是哪个库（MySQL / PostgreSQL / SQL Server 等）。回答后记进领域包，下次不再问。
- **改了 SKILL.md 要重启会话**：Codex / Claude 有缓存，必须退出重进 + 重新 `/skill skill-work` 才生效。
- **分发给同事时**：框架（SKILL.md + protocol + _registry.md）可直接给；领域包只给「基础版」段，`business/` 子目录等项目专属内容不外发。