@wwkit/harness 1.0.9 → 1.0.11

package/skills/lint-ai-fix/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: lint-ai-fix
+description: |
+  对 linter 无法自动修复的违规进行 AI 语义修复。内部管理 fix→验证→复检 的 loop（max 3），
+  每次修改后做语法验证，失败则 git checkout 回滚并记人工处理项。agent 只接收最终输出。
+  适用：lint agent 的 AI 修复阶段，处理 lint-tool-fix 的剩余违规。
+  不适用：linter --fix 可修复的违规（使用 lint-tool-fix）、规则检查（使用 lint-rules-analyze）。
+---
+
+# Lint AI 语义修复
+
+## 工作流模式
+
+内部迭代执行（max 3 轮），4 个阶段。
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| remaining_violations | 是 | array | lint-tool-fix 输出的剩余违规列表 |
+| target_dir | 是 | string | 检查目标目录路径 |
+| root_dir | 是 | string | 工程根目录路径 |
+| primary_language | 是 | string | 主语言（`jsts` 或 `python`） |
+| config_file_path | 是 | string | lint 配置文件路径 |
+
+## 输出
+
+- `ai_fixed_count`：AI 修复的违规数
+- `final_violations`：修复后剩余的违规列表（结构同输入）
+- `manual_items`：无法修复的人工处理项列表，每条含 `{ ...violation, fix_attempted, reason }`
+
+## 内部 Loop（max 3）
+
+```
+inner_round 1: 逐条修复 → 语法验证 → linter 复检
+inner_round 2: 逐条修复 → 语法验证 → linter 复检
+inner_round 3: 逐条修复 → 语法验证 → linter 复检
+
+退出条件:
+  - 0 违规 → 成功退出
+  - 无改进（违规数 >= 轮首） → 退出，输出 manual_items
+  - inner_round = 3 → 超限退出，输出 manual_items
+```
+
+## 阶段一：逐条分析修复
+
+对 `remaining_violations` 中的每条违规：
+
+1. 分析违规规则和上下文
+2. 修改源码文件以消除违规
+3. 记录修改的文件和修复内容
+
+### 修复策略
+
+| 规则类型 | 修复策略 |
+|---------|---------|
+| 未使用变量/import | 删除未使用的声明 |
+| 未定义变量 | 添加定义或修正引用 |
+| debugger 语句 | 删除 debugger |
+| 空语句块 | 添加注释或实现 |
+| 比较使用 None/True/False | 改为 is/is not |
+| 其他规则 | 按规则语义最小改动修复 |
+
+## 阶段二：语法验证
+
+每次修改文件后，执行语法验证：
+
+| 主语言 | 验证命令 |
+|--------|---------|
+| jsts | `node --check {file}` |
+| python | `python3 -m py_compile {file}` |
+
+| 条件 | 动作 |
+|------|------|
+| 语法验证通过 | 继续阶段三 |
+| 语法验证失败 | `git checkout {file}` 回滚，标记为 manual_item，跳过该文件 |
+
+## 阶段三：linter 复检
+
+对所有修改的文件重新执行 linter 检查（同 lint-rules-analyze 命令），获取当前违规数。
+
+## 阶段四：退出判断
+
+| 条件 | 动作 |
+|------|------|
+| 当前违规数 = 0 | 成功退出，输出 ai_fixed_count + 空 final_violations |
+| 当前违规数 >= 轮首违规数 | 无改进退出，输出 final_violations + manual_items |
+| inner_round = 3 | 超限退出，输出 final_violations + manual_items |
+| 否则 | inner_round++，回到阶段一 |
+
+## 输出格式
+
+```
+## AI 修复结果
+
+- AI 修复数: X
+- 最终违规数: X
+- 人工处理项: X
+
+### 修复记录
+| # | 文件 | 规则 | 修复内容 |
+|---|------|------|---------|
+| 1 | src/foo.js | no-unused-vars | 删除未使用变量 x |
+
+### 人工处理项
+| # | 文件 | 行号 | 规则 | 原因 |
+|---|------|------|------|------|
+| 1 | src/bar.js | 20 | no-console | 需确认是否保留 console.log |
+```
+
+## 决策
+
+| 条件 | 动作 |
+|------|------|
+| final_violations 为空 | agent 回到轮尾评分（final_count 应为 0 → 达标） |
+| final_violations 非空 | agent 回到轮尾评分（独立验证） |
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| 源码修改后语法失败 | git checkout 回滚，记 manual_item |
+| linter 复检失败 | 使用上一次的违规列表作为 final_violations |
+| git checkout 失败 | 报错，保留当前状态，记 manual_item |
+| 文件只读 | 记 manual_item，跳过 |
+
+## 一定要做
+
+1. 每次修改后必须做语法验证
+2. 语法验证失败必须 git checkout 回滚
+3. 内部 loop 退出条件清晰（0 违规/无改进/超限）
+4. 输出 manual_items 含 fix_attempted 和 reason
+5. 修复是最小改动，不做重构
+
+## 一定不要做
+
+1. 不要做大规模重构
+2. 不要修改非违规文件的代码
+3. 不要跳过语法验证
+4. 不要在语法验证失败时不回滚
+5. 不要执行网络请求

package/skills/lint-config-setup/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: lint-config-setup
+description: |
+  生成或补全 lint 配置文件。读取语言规则清单，按初始启用规则生成 eslint.config.js 或 ruff.toml。
+  已有配置文件时只追加缺失的启用规则，不覆盖用户自定义规则。
+  适用：lint agent 的配置生成阶段，在规则分析前确保配置文件存在且包含初始规则集。
+  不适用：非 lint 场景的配置生成、手动配置调优。
+---
+
+# Lint 配置生成
+
+## 工作流模式
+
+顺序执行，4 个阶段。
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| root_dir | 是 | string | 工程根目录路径 |
+| primary_language | 是 | string | 主语言（`jsts` 或 `python`） |
+
+## 输出
+
+- `config_file_path`：配置文件绝对路径
+- `enabled_rules`：已启用的规则列表
+- `total_rules`：规则清单中的全量规则数
+- `config_generated`：是否新建配置（true=新建，false=已有补全）
+
+## 阶段一：加载规则清单
+
+读取 `references/languages/{primary_language}.md`，解析规则清单表格：
+
+| 主语言 | 规则文件 | 配置文件名 |
+|--------|---------|-----------|
+| jsts | `references/languages/js.md` | `eslint.config.js` |
+| python | `references/languages/py.md` | `ruff.toml` |
+
+提取所有"初始启用"标记为 ✓ 的规则。
+
+## 阶段二：检查已有配置
+
+检查 `root_dir` 下是否已有配置文件：
+
+| 主语言 | 检查文件 |
+|--------|---------|
+| jsts | `eslint.config.js`、`.eslintrc.json`、`.eslintrc.js` |
+| python | `ruff.toml`、`pyproject.toml`（含 `[tool.ruff]` 段） |
+
+## 阶段三：生成或补全
+
+| 条件 | 动作 |
+|------|------|
+| 无配置文件 | 从模板生成新配置文件，写入初始启用规则，`config_generated = true` |
+| 有配置文件 | 读取已有规则，追加缺失的初始启用规则（不覆盖用户自定义），`config_generated = false` |
+
+### 生成模板
+
+jsts → `eslint.config.js`（flat config 格式）：
+```javascript
+import js from '@eslint/js';
+export default [
+  js.configs.recommended,
+  { rules: { /* 初始启用规则 */ } },
+];
+```
+
+python → `ruff.toml`：
+```toml
+[lint]
+select = ["F401", "F811", "F841", "E711"]
+```
+
+## 阶段四：输出
+
+输出配置文件路径、已启用规则列表、全量规则数、是否新建。
+
+## 决策
+
+| 条件 | 动作 |
+|------|------|
+| 生成/补全成功 | 输出结果，流程结束 |
+| 生成失败 | 报错，agent 退出 |
+| 规则清单文件缺失 | 报错"规则清单文件不存在"，agent 退出 |
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| 规则清单文件不存在 | 报错退出 |
+| 配置文件写入失败 | 报错退出 |
+| 已有配置解析失败 | 报错退出，提示用户检查配置文件格式 |
+
+## 一定要做
+
+1. 从规则清单文件读取初始启用规则
+2. 已有配置只追加缺失规则，不覆盖用户自定义
+3. eslint.config.js 使用 flat config 格式（ESLint 9+）
+4. 输出 config_generated 标识新建 vs 补全
+
+## 一定不要做
+
+1. 不要覆盖用户已有的自定义规则
+2. 不要修改非配置文件
+3. 不要写入初始未启用的规则
+4. 不要执行网络请求

package/skills/lint-config-setup/references/languages/js.md

@@ -0,0 +1,110 @@
+# JS/TS ESLint 规则清单
+
+## 工具信息
+
+| 项 | 值 |
+|---|---|
+| 工具 | ESLint |
+| 安装 | `npm install -D eslint` |
+| TS 扩展 | `npm install -D @typescript-eslint/parser @typescript-eslint/eslint-plugin` |
+| 配置文件 | `eslint.config.js`（flat config，ESLint 9+） |
+| 检查命令 | `npx eslint {target_dir} --format json` |
+| 修复命令 | `npx eslint {target_dir} --fix` |
+| 输出格式 | JSON 数组，每元素含 `filePath` + `messages[]` |
+
+## ESLint JSON 输出解析
+
+```json
+[
+  {
+    "filePath": "/abs/path/to/file.js",
+    "messages": [
+      {
+        "ruleId": "no-unused-vars",
+        "severity": 2,
+        "message": "'x' is defined but never used",
+        "line": 10,
+        "column": 5,
+        "fix": { "range": [100, 110], "text": "" }
+      }
+    ]
+  }
+]
+```
+
+- `severity`: 1 = warning, 2 = error
+- `fix` 存在 = 可自动修复（`fixable = true`）
+
+## 规则清单
+
+> 初始启用标记 ✓ 的规则在配置生成时写入 config 文件；✗ 的规则仅记录在清单中，后续可逐步放开。
+
+### Possible Errors
+
+| 规则 | 描述 | 默认级别 | 初始启用 | 可 fix |
+|------|------|---------|---------|--------|
+| no-unused-vars | 禁止未使用的变量 | error | ✓ | ✗ |
+| no-undef | 禁止未定义的变量 | error | ✓ | ✗ |
+| no-cond-assign | 禁止条件表达式中赋值 | error | ✗ | ✓ |
+| no-debugger | 禁止 debugger 语句 | error | ✓ | ✗ |
+| no-dupe-keys | 禁止对象字面量重复键 | error | ✗ | ✓ |
+| no-dupe-args | 禁止函数参数重复 | error | ✗ | ✓ |
+| no-empty | 禁止空语句块 | error | ✓ | ✓ |
+| no-extra-semi | 禁止多余分号 | error | ✗ | ✓ |
+| no-irregular-whitespace | 禁止不规则的空白字符 | error | ✗ | ✗ |
+| no-unreachable | 禁止 return 后的不可达代码 | error | ✗ | ✓ |
+
+### Best Practices
+
+| 规则 | 描述 | 默认级别 | 初始启用 | 可 fix |
+|------|------|---------|---------|--------|
+| no-console | 禁止 console | warn | ✗ | ✓ |
+| no-constant-condition | 禁止常量条件表达式 | error | ✗ | ✗ |
+| no-dupe-else-if | 禁止重复的 else if | error | ✗ | ✓ |
+| no-empty-pattern | 禁止空解构模式 | error | ✗ | ✓ |
+| no-ex-assign | 禁止 catch 中重新赋值异常 | error | ✗ | ✓ |
+| no-fallthrough | 禁止 switch 穿透 | error | ✗ | ✗ |
+| no-redeclare | 禁止重复声明 | error | ✗ | ✓ |
+| no-useless-return | 禁止无用的 return | error | ✗ | ✓ |
+| eqeqeq | 要求严格相等 === | error | ✗ | ✓ |
+| prefer-const | 优先使用 const | error | ✗ | ✓ |
+
+### Stylistic Issues
+
+| 规则 | 描述 | 默认级别 | 初始启用 | 可 fix |
+|------|------|---------|---------|--------|
+| semi | 分号一致性 | warn | ✗ | ✓ |
+| quotes | 引号一致性 | warn | ✗ | ✓ |
+| indent | 缩进一致性 | warn | ✗ | ✓ |
+| no-trailing-spaces | 禁止行尾空格 | warn | ✗ | ✓ |
+| eol-last | 文件末尾换行 | warn | ✗ | ✓ |
+| no-multiple-empty-lines | 禁止多个空行 | warn | ✗ | ✓ |
+
+### ES6+
+
+| 规则 | 描述 | 默认级别 | 初始启用 | 可 fix |
+|------|------|---------|---------|--------|
+| no-const-assign | 禁止修改 const | error | ✗ | ✗ |
+| no-dupe-class-members | 禁止重复类成员 | error | ✗ | ✓ |
+| no-var | 禁止 var | error | ✗ | ✓ |
+| prefer-arrow-callback | 优先箭头函数回调 | warn | ✗ | ✓ |
+
+## 配置文件模板（eslint.config.js）
+
+```javascript
+import js from '@eslint/js';
+
+export default [
+  js.configs.recommended,
+  {
+    rules: {
+      'no-unused-vars': 'error',
+      'no-undef': 'error',
+      'no-debugger': 'error',
+      'no-empty': 'error',
+    },
+  },
+];
+```
+
+> 仅写入初始启用 ✓ 的规则。用户已有配置文件时只追加缺失规则，不覆盖。

package/skills/lint-config-setup/references/languages/py.md

@@ -0,0 +1,89 @@
+# Python Ruff 规则清单
+
+## 工具信息
+
+| 项 | 值 |
+|---|---|
+| 工具 | Ruff |
+| 安装 | `pip install ruff` 或 `uv add --dev ruff` |
+| 配置文件 | `ruff.toml` |
+| 检查命令 | `ruff check {target_dir} --output-format json` |
+| 修复命令 | `ruff check {target_dir} --fix` |
+| 输出格式 | JSON 数组，每元素含 code/message/filename/location |
+
+## Ruff JSON 输出解析
+
+```json
+[
+  {
+    "code": "F401",
+    "message": "'os' imported but unused",
+    "filename": "/abs/path/to/file.py",
+    "location": [10, 1],
+    "end_location": [10, 10],
+    "fix": null
+  }
+]
+```
+
+- `fix` 非 null = 可自动修复（`fixable = true`）
+- severity 映射：F 前缀 = error，E 前缀 = error，W 前缀 = warning，UP 前缀 = warning
+
+## 规则清单
+
+> 初始启用标记 ✓ 的规则在配置生成时写入 config 文件；✗ 的规则仅记录在清单中，后续可逐步放开。
+
+### Pyflakes (F)
+
+| 规则 | 描述 | 默认级别 | 初始启用 | 可 fix |
+|------|------|---------|---------|--------|
+| F401 | 未使用的 import | error | ✓ | ✓ |
+| F811 | 重定义未使用的名称 | error | ✓ | ✓ |
+| F841 | 未使用的局部变量 | error | ✓ | ✓ |
+| F501 | f-string 无占位符 | error | ✗ | ✓ |
+| F541 | f-string 无占位符 | error | ✗ | ✓ |
+| F601 | 字典字面量重复键 | error | ✗ | ✓ |
+| F621 | 参数列表解包重复 | error | ✗ | ✗ |
+| F622 | 星号后重复参数 | error | ✗ | ✗ |
+| F633 | 非法 __future__ import | error | ✗ | ✗ |
+| F701 | break 在循环外 | error | ✗ | ✗ |
+| F821 | 未定义名称 | error | ✗ | ✗ |
+| F822 | __all__ 中未定义名称 | error | ✗ | ✗ |
+
+### Pycodestyle (E/W)
+
+| 规则 | 描述 | 默认级别 | 初始启用 | 可 fix |
+|------|------|---------|---------|--------|
+| E711 | 比较使用 None 应为 is None | error | ✓ | ✓ |
+| E712 | 比较使用 True/False 应为 is | error | ✗ | ✓ |
+| E713 | not in 应替代 not ... in | error | ✗ | ✓ |
+| E714 | is not 应替代 not ... is | error | ✗ | ✓ |
+| E501 | 行过长（默认 88 字符） | warn | ✗ | ✗ |
+| E302 | 预期 2 个空行 | warn | ✗ | ✓ |
+| E303 | 函数间空行过多 | warn | ✗ | ✓ |
+| E305 | 函数/类后 2 个空行 | warn | ✗ | ✓ |
+| W291 | 行尾空格 | warn | ✗ | ✓ |
+| W292 | 文件末尾无换行 | warn | ✗ | ✓ |
+| W293 | 空行有空白字符 | warn | ✗ | ✓ |
+
+### Pyupgrade (UP)
+
+| 规则 | 描述 | 默认级别 | 初始启用 | 可 fix |
+|------|------|---------|---------|--------|
+| UP001 | 过时的 __future__ import | warn | ✗ | ✓ |
+| UP010 | 过时的 __future__ union types | warn | ✗ | ✓ |
+| UP011 | 不必要的 lru_cache 括号 | warn | ✗ | ✓ |
+| UP015 | 不必要的 open 模式 | warn | ✗ | ✓ |
+
+## 配置文件模板（ruff.toml）
+
+```toml
+[lint]
+# 初始启用规则
+select = ["F401", "F811", "F841", "E711"]
+
+[lint.fix]
+unsafe-fixes = false
+```
+
+> 仅写入初始启用 ✓ 的规则。用户已有配置文件时只追加缺失规则，不覆盖。

package/skills/lint-env-ensure/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: lint-env-ensure
+description: |
+  检查 lint 工具可用性，缺失时在项目内自动安装。按主语言检查对应 linter（jsts→eslint，python→ruff），
+  安装失败重试 3 次。加载配置清单供后续 skill 共享。
+  适用：lint agent 的环境检查阶段，在配置生成和规则分析前确保工具可用。
+  不适用：非 lint 场景的环境检查、系统级工具安装。
+---
+
+# Lint 环境检查
+
+## 工作流模式
+
+顺序执行，4 个阶段。
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| root_dir | 是 | string | 工程根目录路径 |
+| primary_language | 是 | string | 主语言（`jsts` 或 `python`） |
+
+## 输出
+
+- `linter_name`：linter 名称（`eslint` 或 `ruff`）
+- `linter_version`：linter 版本号
+- `linter_installed`：是否已安装且可用（bool）
+- `config`：从 references/config.md 加载的配置对象
+
+## 阶段一：检查工具可用性
+
+按 `primary_language` 检查对应 linter：
+
+| 主语言 | linter | 检查命令 |
+|--------|--------|---------|
+| jsts | eslint | `npx eslint --version` |
+| python | ruff | `ruff --version` |
+
+## 阶段二：自动安装（工具缺失时）
+
+工具不可用时，在项目内安装：
+
+| 主语言 | 安装命令 | 备注 |
+|--------|---------|------|
+| jsts | `cd {root_dir} && npm install -D eslint` | TS 项目额外安装 `@typescript-eslint/parser @typescript-eslint/eslint-plugin` |
+| python | `cd {root_dir} && pip install ruff` 或 `cd {root_dir} && uv add --dev ruff` | 优先用 uv，回退到 pip |
+
+安装失败时重试，最多 3 次（`install_retry` 来自 config）。
+
+## 阶段三：安装验证
+
+重新执行阶段一的检查命令，确认安装成功。
+
+| 条件 | 动作 |
+|------|------|
+| 工具可用 | 输出 linter_name/version/installed=true，继续 |
+| 工具仍不可用 | 输出 installed=false，agent 退出 |
+
+## 阶段四：加载配置
+
+读取 `references/config.md`，输出配置对象供后续 skill 使用。
+
+## 决策
+
+| 条件 | 动作 |
+|------|------|
+| 工具已安装 | 输出结果，流程结束 |
+| 工具缺失，安装成功 | 输出结果，流程结束 |
+| 工具缺失，安装失败 | 输出 installed=false，agent 退出 |
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| 检查命令执行失败 | 认为工具未安装，进入安装流程 |
+| npm install 失败 | 重试最多 3 次 |
+| pip install 失败 | 尝试 uv add，再失败则重试 |
+| 重试 3 次仍失败 | 输出 installed=false |
+
+## 一定要做
+
+1. 在项目内安装（`npm install -D`），不安装全局
+2. 安装后必须重新验证工具可用性
+3. 加载 config.md 配置供后续 skill 共享
+4. TS 项目检查是否需要 @typescript-eslint 插件
+
+## 一定不要做
+
+1. 不要全局安装工具（`npm install -g`）
+2. 不要跳过安装验证步骤
+3. 不要修改项目配置文件（package.json 等）
+4. 不要使用 webfetch 下载工具，仅通过包管理器（npm/pip/uv）安装

package/skills/lint-env-ensure/references/config.md

@@ -0,0 +1,65 @@
+# lint 检查代理配置清单
+
+> 本文件是 lint 代理的全局配置，agent 启动时首先读取，后续所有 skill 共享。
+
+## 依赖工具
+
+### JS/TS
+
+| name | check | required | install |
+|------|-------|----------|---------|
+| eslint | `npx eslint --version` | true | `npm install -D eslint` |
+| @typescript-eslint/parser | `npx tsc --version` 时需要 | false | `npm install -D @typescript-eslint/parser @typescript-eslint/eslint-plugin` |
+
+### Python
+
+| name | check | required | install |
+|------|-------|----------|---------|
+| ruff | `ruff --version` | true | `pip install ruff` 或 `uv add --dev ruff` |
+
+## 环境检查
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| install_retry | 3 | 工具安装失败重试次数 |
+
+## Loop 控制
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| outer_max | 3 | 外层 loop（check→fix→recheck）最大轮次 |
+| inner_max | 3 | lint-ai-fix 内部 loop 最大轮次 |
+
+## 评分模型
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| target_score | 100 | 二元制：0 违规=100，1+ 违规=0 |
+| pass_threshold | 0 | 违规数达标线（0 = 全部通过） |
+
+## 命名规则
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| report_dir_pattern | `{root_dir}/.webwork/harness/lint/{YYYY-MM-DD}/` | 报告输出目录 |
+| report.lint_report | `lint_report-{HHMMSS}.md` | 最终报告文件名 |
+
+## 语言映射
+
+| 语言 | 标识 | 扩展名 | manifest | linter | config_file |
+|------|------|--------|----------|--------|-------------|
+| JS/TS/Vue | jsts | .js .jsx .ts .tsx .vue .mjs .cjs | package.json | eslint | eslint.config.js |
+| Python | python | .py | pyproject.toml / setup.py | ruff | ruff.toml |
+
+## 排除目录
+
+```
+node_modules/ dist/ build/ .git/ __pycache__/ .venv/ venv/ .webwork/ reports/ coverage/ .next/ .nuxt/ .output/ .eggs/ eggs/
+```
+
+## 语法验证命令
+
+| 语言 | 命令 | 说明 |
+|------|------|------|
+| jsts | `node --check {file}` | Node.js 语法检查 |
+| python | `python3 -m py_compile {file}` | Python 字节码编译检查 |

package/skills/lint-language-detect/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: lint-language-detect
+description: |
+  探测工程主语言。优先检查 manifest 文件（package.json → jsts，pyproject.toml/setup.py → python），
+  无 manifest 时按源码文件扩展名计数，多者为主语言。JS/TS 视为一种语言。
+  适用：lint agent 的语言探测阶段，在环境检查和配置生成前确定主语言。
+  不适用：非 lint 场景的语言检测、混合语言项目（v1 按主语言处理，不支持混合）。
+---
+
+# 主语言探测
+
+## 工作流模式
+
+顺序执行，2 个阶段。
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| root_dir | 是 | string | 工程根目录路径 |
+
+## 输出
+
+- `primary_language`：主语言标识（`jsts` 或 `python`）
+- `detection_method`：检测方式（`manifest` 或 `file_count`）
+- `file_counts`：各语言源码文件计数（仅 `file_count` 方式时有值）
+
+## 阶段一：Manifest 检测
+
+检查 `root_dir` 下的 manifest 文件：
+
+| 检查项 | 命中结果 |
+|--------|---------|
+| `package.json` 存在 | `primary_language = jsts`，`detection_method = manifest` |
+| `pyproject.toml` 存在 | `primary_language = python`，`detection_method = manifest` |
+| `setup.py` 存在 | `primary_language = python`，`detection_method = manifest` |
+
+若 manifest 命中，直接输出结果，跳过阶段二。
+
+## 阶段二：文件计数检测
+
+无 manifest 时，调用 `references/detect-language.js` 的 `detectLanguage(rootDir)` 函数扫描源码文件：
+
+1. 递归扫描 `root_dir`（最大深度 10 层）
+2. 排除目录：`node_modules/`、`dist/`、`build/`、`.git/`、`__pycache__/`、`.venv/`、`venv/`、`.webwork/`、`reports/`、`coverage/`
+3. 按扩展名分类计数：
+   - jsts：`.js`、`.jsx`、`.ts`、`.tsx`、`.vue`、`.mjs`、`.cjs`
+   - python：`.py`
+4. 文件数多者为主语言；两者都为 0 → 报错
+
+## 决策
+
+| 条件 | 动作 |
+|------|------|
+| manifest 命中 | 输出主语言，流程结束 |
+| 无 manifest，源码文件 > 0 | 输出计数多者为主语言 |
+| 无 manifest，源码文件 = 0 | 报错退出 |
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| root_dir 不存在 | 报错"工程根目录不存在" |
+| 无 manifest 且无源码文件 | 报错"无法检测项目主语言" |
+| 扫描权限不足 | 跳过不可读目录，继续扫描 |
+
+## 一定要做
+
+1. 优先检查 manifest 文件，避免全量扫描
+2. JS/TS 统一视为 `jsts` 一种语言
+3. 排除常见的非源码目录
+4. 无 manifest 时必须扫描文件计数
+
+## 一定不要做
+
+1. 不要返回多个语言（v1 只返回主语言）
+2. 不要扫描 `node_modules/` 等依赖目录
+3. 不要修改任何文件
+4. 不要执行网络请求