# 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-11-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# skill-work 使用说明

> 一套**通用工作知识框架**：约束 AI 怎么组织知识、怎么干活、怎么沉淀。
> **本文件是产品说明书，给人看**——怎么装、怎么用、遇到问题怎么办，全在这里。
> AI 的工作规则在 `SKILL.md`（AI 不靠本文件指导工作，只基于 skill 本体）。
> **归属**：TRUNK

## 这是什么

一个**不绑定任何技术**的框架：它只定义 5 类空槽位（见下「五类工作知识」），具体内容由**领域包**填充。你换方向（比如从后端开发换到 AI 应用），**框架一个字不用改**——新建一个领域包并切换激活即可。

- **给人用**：规范你的项目知识组织方式，AI 产出前先读规范、产出后自动留痕，改了什么、为什么改都有据可查
- **给 AI 用**：启动即建好目录结构、按内容类型路由一切写入、每个流程都有契约头（AI 必读的前置/决策点/产出约束）
- **给自己兜底**：带一套机器门禁（健康自检 / 回归 / 审计），改动是否合规**由脚本判定，不靠 AI 自觉**

## 一张图看懂组织架构

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

三层结构：**入口层**（SKILL.md，只放规则与路由）→ **注册表**（_registry.md，一切路径唯一入口）→ **三大模块**（协议 / 脚本 / 领域包）。机器门禁把规则变成可拦截的检查，三级同步保证多环境不漂移。

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

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

- [ ] **Python 3.9+**——跑 scripts/ 下的自检/同步/检查脚本
  - 验证：`py --version`（或 `python --version`）应 ≥ 3.9；Windows 若 `python` 不在 PATH 用 `py` 启动器
- [ ] **Git**——生成 commit message 时从真实 git 记录取数，禁凭记忆编造；不用 git 的项目可跳过
- [ ] **PowerShell 5.1+**（Windows）/ **bash 4+**（macOS / Linux）——初始化预检用

### ✅ 必建（结构）

结构 = 桌面 `dj-work-skills/skill-work/`（最终源）＋各工具用户级副本。**完整目录树见「目录结构」节**。

首次同步（让当前 AI 工具拿到副本）：

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

# 2. 验证（应全 PASS）
<PY> references/domains/<包>/scripts/check-standards.py <目标目录>
```

### ✅ 必配（领域包）

框架不绑定任何技术。**必须有一个激活领域包**（领域知识全在包里）；没有激活包时框架会**停下问你**：新建包，还是先给资料。

- **激活领域包由你显式选择**（见 `_registry.md §2`），AI 不会自作主张按工作内容自动激活
- 没有合适的领域包？→ 走「新建领域包」流程（问 6 项，见 `references/protocol/references.md §9` + `protocol/skill-change.md`）
- **激活即入戏**：每个领域包声明「角色定位」，AI 加载后以该领域最懂业务/最懂技术的人的身份作业（只借方法不借值）

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

- [ ] **UTF-8 终端**（避免 Windows 乱码）：PowerShell 执行 `[Console]::OutputEncoding = [System.Text.Encoding]::UTF8`，可写进 `$PROFILE` 永久化
- [ ] **Codex / Claude / WorkBuddy / Trae CN / DeepSeek Harness 任一客户端**——本 skill 是给 AI 用的，须在能加载 skill 的工具里跑
- [ ] **git 配好 user.name / user.email**——生成 commit message 时用来核对作者

### ❌ 不需要

- ❌ 任何特定 IDE（规则与编辑器无关）
- ❌ 网络（除非要同步多台机器 / 推送到远程）

### ✅ 可选：数据库验证工具（database-agent，随仓库分发）

本仓库 `tools/database-agent/` 内置 **database-validation** 工具（只读、受策略控制的数据库验证 MCP server），查数据优先用它（连库流程见 `references/domains/<id>/data-query.md`；凭据纪律见 `tools/database-agent/RULES.md`「凭据（强制）」节，连接信息项目级自治）。

> **来源与版本**：database-agent **0.1.0**（分享包 `database-agent-0.1.0+codex.20260914120000-share.zip`，2026-09-30 嵌入）。上游更新时按本版本号比对，防静默漂移。

**安装（3 步）**：

```powershell
# 1) 创建虚拟环境并安装（需要 Python 3.11+）
cd 你的项目目录
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e "C:\path\to\skill-work\tools\database-agent[server]"

# 2) 数据库驱动（按你的库装，可选）
pip install dmPython          # 达梦
pip install psycopg2-binary   # 人大金仓 KingbaseES
pip install PyMySQL           # MySQL
python -c "import dmPython; print(dmPython.__file__)"   # 验证

# 3) 项目初始化 + 填自己的连接
database-agent init --project-root <项目根>
# 编辑 <项目根>/.dsh/connections.yaml（2026-11-13 统一落点）：密码用 ${DB_*} 环境变量引用，不写明文
# 字段用 username（MCP 硬契约）；旧 .database-agent/connections.yaml 仍兼容读取
```

**纪律**：工具是通用的、配置是各自的——**绝不把真实连接信息提交进仓库**（`.database-agent/` 已入 .gitignore）；连接仅为查数据（只读），禁止任何修改。

## 安装到工具（3 步）

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

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

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

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

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

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

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

## 日常怎么用

| 你说 | AI 做什么 |
|---|---|
| `dj` / `你好` | 跑初始化：建目录、校验内容类型、报状态 |
| 「补充 XX 方法」 | 读规范基线 → 产出 → 跑检查修到 PASS → 回写对应文件 → 记日志 |
| 「生成提交记录」 | 从 git 读改动 → 生成 commit message **给你确认**，**不会自动提交** |
| 「补充 XX 到 skill」 | 判断属于哪一类 → 去重后写入 |
| 「看 token 用量」 | `<PY> scripts/session-token-report.py --all-projects --gate`，超阈值提示 /compact 或开新会话 |
| 「今天改了什么」 | 从 git 取当天提交，汇总给你 |
| 「换领域 / 新方向」 | 问你 6 项 → 建新领域包 → 切注册表（SKILL.md 不动） |

## 五类工作知识

框架把一切工作知识划分为 **5 类**——这是知识分类判据（**不是目录、不是编号**），实际放哪个文件由领域包的 `DOMAIN.md §3` 决定：

| 类别 | 记什么 | 谁提供 | 项目里怎么放 |
|---|---|---|---|
| **规范与约束** `standards` | 规范底线（命名、格式、禁用写法） | 基线=框架自带；补充=领域包 | **全局唯一**——项目里完全不建，只读引用 |
| **工具与技术** `tooling` | 工具与技术（怎么调用、踩过什么坑） | 领域包 | 同步一份只读参考 |
| **领域事实** `context` | 领域事实（背景、上下游、关键决策）+ 项目附加约定 | 领域包 | 项目专属 |
| **流程 SOP** `playbook` | 流程 SOP（重复性操作的标准步骤） | 领域包 | 项目专属 |
| **错题库** `errors` | 踩过的坑（现象 / 原因 / 处置），分「本领域通用」与「单项目专属」两级 | 领域包 | 项目专属 |

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

## 目录结构

```
skill-work/
├── SKILL.md                        # 通用内核：规则 + 路由（不含任何领域值）
├── README.md                       # 本文件，产品说明书（给人看）
├── docs/
│   └── architecture.svg            # 组织架构图
├── references/

│   ├── _registry.md                # 内容注册表 ⭐ 一切路径的入口
│   ├── checker-declarations.md     # 机检声明区（checker 启动读取）
│   ├── quickstart.md               # 5 行速览指针
│   ├── improvement-backlog.md      # 反馈累积池
│   ├── CHANGELOG.md                # skill 自身演进日志（每条 ≤10 行）
│   ├── domains/<包>/errors.md       # ⭐ 领域错题库（报错关键词索引，先查这里）
│   ├── protocol/                   # 5 个内核协议
│   │   ├── workflow.md             #   写代码的流程（查规范 → 写 → 跑脚本）
│   │   ├── skill-change.md         #   改 skill 的流程（影响面五问 / 动手四问 / 落点判定）
│   │   ├── project-init.md         #   项目级 skill 初始化 + 三层同步（L0/L1/项目）
│   │   ├── references.md           #   引用治理 / 内容归属
│   │   └── testing/skill-test-scenarios.md  # 测试体检 / 回归场景表
│   └── domains/<id>/               # 领域包（可并存多个，同时激活一个）
│       ├── DOMAIN.md               # 领域清单：已确定什么、必须问什么
│       ├── standards-addendum.md   # 规范补充（只能补充/收紧）
│       ├── tech-stack-usage.md     # 工具与技术（主线技术栈）
│       ├── legacy-stack-usage.md   # 工具与技术（存量手写栈）
│       ├── business-summary.md     # 领域事实
│       ├── data-migration.md       # 流程 SOP（迁移）
│       ├── data-query.md           # 流程 SOP（迁移）（查库）
│       ├── migration/              #   迁移场景剧本 / 脚本规范 / 文件夹规范
│       └── business/<项目>/        #   ⭐ 项目业务明细：business.md + tables.md + platform.md (+ errors.md)
│   ├── check-skill-health.py       # ⭐ 健康自检（启动必跑，FAIL 先修）
│   ├── skill-audit.py              # 自审候选 + --clean 清理清单
│   ├── check-drift.py              # 三级同步差异检测
│   ├── sync-desktop.py             # ⭐ 桌面 SSOT ↔ L1 双向同步（--direction L0toL1|L1toL0）
│   ├── one-click-init.py           # 一键初始化
│   ├── run-regression.py           # 回归测试（发版前必跑）
│   ├── check-standards.py          # 基线自动检查（--show 展示适用规范清单）
│   ├── check-integrity.py          # 字面完整性 I1–I4（残缺词/拆行/路径/行号指针）
│   ├── check-platform-dup.py       # 通用↔项目分界 PD1–PD3（platform.md 禁复述 tech-stack）
│   ├── session-token-report.py     # 会话 token 用量报告（--gate 闸门）
│   └── record-issue.py             # 失败/自检自动记 backlog
└── (fix-desktop-junction.py / sync-to-desktop.py 为兼容转发壳，指向 sync-desktop.py)
```

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

> **本节只是给人看的速览。方向和门槛的唯一真源在 [`references/protocol/project-init.md`](references/protocol/project-init.md)（协议 ID `DESKTOP-MIRROR`）**——那里有完整的三级位置表、两个同步流向（方向 A 现场修改流 / 方向 B 知识沉淀）、同步决策门槛和命令清单。本节若与它冲突，**以 `project-init.md` 为准**。

| 级别 | 位置 | 一句话 |
|---|---|---|
| **L0 桌面 SSOT** | `<桌面>\dj-work-skills\skill-work\` | 最终基准，备份就复制整个目录 |
| **L1 工具用户级** | `~/.codex` / `~/.claude` / `~/.workbuddy` / `~/.trae-cn` / `$DSH_HOME` 的 `skills/skill-work/` | 当前工具的工作副本，实际加载的就是它 |
| **L2 项目级** | `<项目>/.<tool>/`：领域模型 = `skill/` + `chatLog/{sql,doc}`；（v10.5.0 起无通用模型，无激活包即报错退出） | 项目私有知识（`skill/` 三文件分卷 = 业务/表结构/平台机制第一手战场）+ 产物（`chatLog/`） |

- **改规范**：先改 **L1 现场**并验证 → **当日回写 L0**（差异清单 + 授权）→ L0 再分发；项目级没有规范修改权
- **分发**（换工具 / 新项目 / 换机）：L0 → L1 → L2（规范不复制进项目，只读引用）
- **沉淀**（新知识）：L2 → L1 → L0；**项目专属不上浮**，只有通用规则，且需你授权

> ⚠️ **三义别混**：**回写 L0**（L1→L0）｜**分发**（L0→其他 L1）｜**上浮**（L2→L1→L0 沉淀）——方向相反，用词不可互换。

## 常见问题

**Windows 路径小坑（Git Bash 用户必看）**

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

**改了 SKILL.md 要重启会话**

Codex / Claude 有缓存，改完 SKILL.md 必须退出重进 + 重新 `/skill skill-work` 才生效。

**分发给同事时**

框架（SKILL.md + protocol + _registry.md）可直接给；领域包只给「基础版」段，`business/` 子目录等项目专属内容不外发。

**机制会自我治理，改动有机器把关**

框架自带自治理闭环（五自我：检查/思考/清洁/优化/约束），每个自我都有脚本抓手——`check-skill-health.py`（治理门禁 G 系 + 提示 H 系 + 引用检查 R/K）、`skill-audit.py`（自审候选，删除类须你逐条授权）、`run-regression.py`（回归）、`check-standards.py`（规范检查）。**改动是否合规由脚本判定，不靠 AI 自觉**；真问题自动落 `improvement-backlog.md` 待你评审。回归场景数与机判/半自动/人工分布以 `references/protocol/testing/skill-test-scenarios.md` 场景表实计为准，每次回归打印机判覆盖率（不写文件）。

## 生产定位

生产工具——核心使命是帮你**写代码、跑项目、快准稳**。维护政策（机制冻结宣言：检查器 / 协议 / 规则**只修不增**）见 `references/protocol/skill-change.md §7`。