@haaaiawd/anws 1.2.4 → 2.0.0

package/templates/.agents/skills/nexus-mapper/references/language-customization.md

@@ -0,0 +1,164 @@
+# 为 nexus-mapper 补充语言支持
+
+> 本文件不是阶段门控文件。当内置语言覆盖不足时，后续 agent 应优先参考本文件，通过命令行参数补充支持；只有在配置较复杂时，才使用显式 JSON 配置文件。
+
+---
+
+## 目标
+
+当前脚本的默认模型是：
+
+1. 先使用内置扩展名映射和内置 Tree-sitter query
+2. 若内置覆盖不足，再由 agent 通过命令行补充语言支持
+3. 若命令行参数过多或 query 过长，再退回到 `--language-config <JSON_FILE>`
+
+这意味着：
+- 不要求仓库内必须存在固定路径的语言配置文件
+- 不建议为了单个仓库的单次分析先改核心脚本
+- 新接手的 agent 可以在一次命令中直接把额外语言接入分析流程
+
+---
+
+## 优先方案：命令行补充
+
+### 适用场景
+
+满足以下条件时，优先用命令行：
+
+- 仓库里出现了内置未覆盖的扩展名
+- 只需要补 1 到 3 个语言映射
+- query 较短，适合直接写在命令行中
+
+### 步骤 1：确认语言名
+
+先确认 `tree-sitter-language-pack` 或当前环境可识别的语言名。例如：
+
+- `.templ` -> `templ`
+- `.hbs` -> `handlebars`
+- `.rego` -> `rego`
+
+如果语言名不确定，先查官方 grammar 名称；不要猜测一个语言名直接写入最终结论。
+
+### 步骤 2：补扩展名映射
+
+```bash
+python extract_ast.py <repo_path> \
+  --add-extension .templ=templ \
+  --add-extension .hbs=handlebars
+```
+
+这会把原本不认识的扩展名纳入语言分发流程。
+
+### 步骤 3：按需补 query
+
+如果只需要 Module 级覆盖，可以到此为止。
+
+如果需要类/函数级结构，继续追加 `--add-query`：
+
+```bash
+python extract_ast.py <repo_path> \
+  --add-extension .templ=templ \
+  --add-query templ struct "(component_declaration name: (identifier) @class.name) @class.def"
+```
+
+参数格式：
+
+```text
+--add-query <LANG> <TYPE> <QUERY_STRING>
+```
+
+其中：
+- `<LANG>`：语言名，例如 `templ`
+- `<TYPE>`：`struct` 或 `imports`
+- `<QUERY_STRING>`：Tree-sitter query 字符串
+
+capture 命名必须继续遵守现有约定：
+- 类：`@class.def` / `@class.name`
+- 函数：`@func.def` / `@func.name`
+- 导入：`@mod`
+
+---
+
+## 备选方案：显式 JSON 配置文件
+
+当下面任一情况成立时，可使用 `--language-config`：
+
+- 需要补多个语言，命令行已经过长
+- query 很复杂，不适合内联在 shell 命令里
+- 希望把一次分析所需的扩展映射和 query 集中保存
+
+示例：
+
+```json
+{
+  "extensions": {
+    ".templ": "templ",
+    ".hbs": "handlebars"
+  },
+  "queries": {
+    "templ": {
+      "struct": "(component_declaration name: (identifier) @class.name) @class.def",
+      "imports": ""
+    }
+  },
+  "unsupported_extensions": {
+    ".legacydsl": "legacydsl"
+  }
+}
+```
+
+执行方式：
+
+```bash
+python extract_ast.py <repo_path> --language-config /custom/path/to/language-config.json
+```
+
+说明：
+- `extensions`：扩展名到语言名的映射
+- `queries`：自定义 `struct` / `imports` query
+- `unsupported_extensions`：显式声明当前仍不支持的扩展名，避免静默跳过
+
+这里的 JSON 文件是一次分析的显式输入，不要求固定放在仓库某个默认位置。
+
+---
+
+## 覆盖诚实度规则
+
+不管是命令行还是显式 JSON，新增语言都必须遵守同一套分层标准：
+
+1. `structural coverage`
+   条件：parser 可加载，且存在 `struct` query
+
+2. `module-only coverage`
+   条件：parser 可加载，但没有 `struct` query
+
+3. `configured-but-unavailable`
+   条件：agent 明确要求支持该语言，但当前环境无法加载 parser
+
+4. `unsupported`
+   条件：该语言仍未纳入本次 AST 流程，或被显式标记为未支持
+
+禁止：
+- 把 `configured-but-unavailable` 写成 `module-only`
+- 把 `unsupported` 伪装成“仓库里没出现”
+
+---
+
+## 推荐决策顺序
+
+当后续 agent 遇到一个未覆盖语言时，按以下顺序处理：
+
+1. 先确认当前仓库里是否真的存在该扩展名文件
+2. 再确认当前环境能否加载对应 parser
+3. 若能加载：优先用 `--add-extension`；需要结构节点时再补 `--add-query`
+4. 若命令太长：改用 `--language-config`
+5. 若 parser 不能加载：保留 `configured-but-unavailable`，不要伪造结果
+
+---
+
+## 设计原则
+
+- 内置语言优先，命令行补充其次，显式 JSON 最后
+- 对单次分析，优先使用最小额外输入，不要先改核心脚本
+- 自定义 query 是正式输入，不是旁路 hack
+- 所有新增语言都必须遵守同一套 metadata 和 provenance 规则

package/templates/.agents/skills/nexus-mapper/references/output-schema.md

@@ -0,0 +1,298 @@
+# 输出 Schema 规范
+
+> **EMIT 阶段硬门控**：本文件由 `probe-protocol.md` 的 EMIT 阶段门控强制触发读取，
+> 写入任何 `.nexus-map/` 文件前必须完成本文阅读。
+> 本文 Schema 均基于实际运行输出校正，与脚本当前版本保持一致。
+
+---
+
+## raw/ast_nodes.json（extract_ast.py 产出）
+
+### 顶层结构
+```json
+{
+  "languages": ["cpp", "python"],
+  "stats": {
+    "total_files": 101,
+    "total_lines": 23184,
+    "parse_errors": 0,
+    "truncated": true,
+    "truncated_nodes": 298,
+    "supported_file_counts": {"python": 101},
+    "languages_with_structural_queries": ["python", "javascript", "typescript"],
+    "languages_with_custom_queries": ["gdscript"],
+    "module_only_file_counts": {"vue": 12},
+    "known_unsupported_file_counts": {"customdsl": 24},
+    "configured_but_unavailable_file_counts": {"templ": 6},
+    "custom_language_config_paths": ["/custom/path/to/language-config.json"]
+  },
+  "warnings": [
+    "custom language configuration loaded: /custom/path/to/language-config.json",
+    "some languages were parsed with module-only coverage because no structural query template is bundled: vue (12 files)",
+    "known unsupported languages present; downstream outputs must mark inferred sections explicitly: customdsl (24 files)",
+    "some configured languages were detected in source files but no parser could be loaded: templ (6 files)"
+  ],
+  "nodes": [...],
+  "edges": [...]
+}
+```
+
+### Module 节点
+```json
+{
+  "id": "src.nexus.application.weaving.treesitter_parser",
+  "type": "Module",
+  "label": "treesitter_parser",
+  "path": "src/nexus/application/weaving/treesitter_parser.py",
+  "lines": 320,
+  "lang": "python"
+}
+```
+
+### Class 节点
+```json
+{
+  "id": "src.nexus.application.weaving.treesitter_parser.TreeSitterParser",
+  "type": "Class",
+  "label": "TreeSitterParser",
+  "path": "src/nexus/application/weaving/treesitter_parser.py",
+  "parent": "src.nexus.application.weaving.treesitter_parser",
+  "start_line": 15,
+  "end_line": 287
+}
+```
+
+### Edge
+```json
+{
+  "source": "src.nexus.infrastructure",
+  "target": "src.nexus.infrastructure.db_client",
+  "type": "contains"
+}
+```
+
+**Edge 类型**：`contains`（模块→类，类→方法）/ `imports`（import 语句解析）
+
+### warnings 字段
+
+`warnings` 是可选数组，用来暴露不会导致 PROFILE 失败、但会影响下游可信度的降级信息，例如：
+- grammar 可加载，但当前仅有 Module 级覆盖
+- 已知但未支持的语言存在
+- AST 被截断
+- 部分解析器不可用
+
+### 覆盖分层字段
+
+| 字段                                     | 含义                                                              |
+| ---------------------------------------- | ----------------------------------------------------------------- |
+| `supported_file_counts`                  | 成功进入 AST 流程的文件数（含完整结构覆盖和 module-only 覆盖）    |
+| `languages_with_structural_queries`      | 当前 bundled query 模板覆盖到的语言                               |
+| `languages_with_custom_queries`          | 通过 `--add-query` 或 `--language-config` 新增或覆盖 query 的语言 |
+| `module_only_file_counts`                | grammar 可加载，但当前没有结构 query，只产出 Module 节点的语言    |
+| `known_unsupported_file_counts`          | 已知存在但完全未进入 AST 流程的语言                               |
+| `configured_but_unavailable_file_counts` | agent 明确要求支持该语言，但当前环境没有可用 parser               |
+| `custom_language_config_paths`           | 本次实际加载的显式语言配置文件路径；纯 CLI 模式下为空             |
+
+---
+
+## raw/git_stats.json（git_detective.py 产出）
+
+```json
+{
+  "analysis_period_days": 90,
+  "stats": {
+    "total_commits": 42,
+    "total_authors": 1
+  },
+  "hotspots": [
+    {"path": "src/nexus/tasks/analysis_tasks.py", "changes": 21, "risk": "high"}
+  ],
+  "coupling_pairs": [
+    {"file_a": "...", "file_b": "...", "co_changes": 5, "coupling_score": 0.71}
+  ]
+}
+```
+
+**risk 阈值**：`changes < 5` → `low` / `5–15` → `medium` / `> 15` → `high`
+
+---
+
+## 生成的 Markdown 文件头部
+
+`INDEX.md`、`arch/*.md`、`concepts/domains.md`、`hotspots/git_forensics.md` 的头部至少包含：
+
+```markdown
+> generated_by: nexus-mapper v2
+> verified_at: 2026-03-07
+> provenance: AST-backed except where explicitly marked inferred
+```
+
+如存在语言降级或人工推断，`provenance` 必须扩展说明：
+
+```markdown
+> provenance: AST-backed for Python; some custom DSL files were detected but not parsed by bundled AST tooling, so the affected dependency notes below are inferred from file tree and manual inspection.
+```
+
+---
+
+## concepts/concept_model.json — Schema V1
+
+Schema V1 的人类可读名称字段只有 `label`，不要额外引入 `title`；若出现 `title`，视为非规范字段，应删除。
+
+```json
+{
+  "$schema": "nexus-mapper/concept-model/v1",
+  "generated_at": "2026-03-05T15:00:00Z",
+  "repo_path": "/absolute/path/to/repo",
+  "generator": "nexus-mapper v2",
+  "nodes": [
+    {
+      "id": "nexus.ast-extractor",
+      "type": "System",
+      "label": "AST Extractor",
+      "responsibility": "使用 Tree-sitter 解析 Python 仓库，提取模块/类/函数节点及 import 关系，输出机器可读 JSON",
+      "implementation_status": "implemented",
+      "code_path": "src/nexus/application/weaving/",
+      "evidence_path": null,
+      "evidence_gap": null,
+      "tech_stack": ["tree-sitter", "python"],
+      "related_reqs": ["REQ-101"],
+      "complexity": "medium",
+      "hotspot": true
+    }
+  ],
+  "edges": [
+    {
+      "source": "nexus.ast-extractor",
+      "target": "nexus.task-dispatcher",
+      "type": "depends_on",
+      "description": "可选说明"
+    }
+  ],
+  "metadata": {
+    "total_files": 101,
+    "total_lines": 23184,
+    "languages": ["python"],
+    "git_commits_analyzed": 42,
+    "analysis_days": 90
+  }
+}
+```
+
+### 节点字段校验规则
+
+| 字段                    |   必需   | 触发 `[!ERROR]` 的情况                                                      |
+| ----------------------- | :------: | --------------------------------------------------------------------------- |
+| `id`                    |    是    | 全局重复；含大写字母或空格（必须为 kebab-case 小写）                        |
+| `type`                  |    是    | 不在枚举 `System / Domain / Module / Class / Function` 中                   |
+| `label`                 |    是    | 空字符串                                                                    |
+| `title`                 |    否    | Schema V1 不定义该字段；若写入，视为多余字段                                |
+| `responsibility`        |    是    | 空泛到无法验证；字数 < 10 或 > 120                                          |
+| `implementation_status` |    是    | 不在枚举 `implemented / planned / inferred` 中                              |
+| `code_path`             | 条件必需 | `implementation_status=implemented` 但为空；或路径在 repo 中不实际存在      |
+| `evidence_path`         | 条件必需 | `implementation_status=planned/inferred` 但为空；或路径在 repo 中不实际存在 |
+| `evidence_gap`          | 条件必需 | `implementation_status=planned/inferred` 但为空                             |
+
+### 节点状态表达规范
+
+**已实现节点**
+```json
+{
+  "implementation_status": "implemented",
+  "code_path": "src/server/",
+  "evidence_path": null,
+  "evidence_gap": null
+}
+```
+
+**计划中节点**
+```json
+{
+  "implementation_status": "planned",
+  "code_path": null,
+  "evidence_path": "docs/architecture.md",
+  "evidence_gap": "设计文档提到 Monarch/Executor，但仓库中未发现 src/agents/monarch/"
+}
+```
+
+**推断节点**
+```json
+{
+  "implementation_status": "inferred",
+  "code_path": null,
+  "evidence_path": "docs/architecture.md",
+  "evidence_gap": "仓库包含当前未支持的 DSL 文件；此边界来自文件树与人工阅读"
+}
+```
+
+---
+
+## query_graph.py 输出格式参考（stdout，非写入文件）
+
+### --file
+
+```
+=== <file_path> ===
+Module: <module_id> (<lines> lines, <lang>)
+
+Classes:
+  <ClassName> (L<start>-L<end>)
+    ├─ <method_name> (L<start>-L<end>)
+    └─ <method_name> (L<start>-L<end>)
+
+Top-level Functions:
+  <func_name> (L<start>-L<end>)
+
+Imports:
+  → <internal_module> (<path>)
+  → <external_package> (external)
+```
+
+### --who-imports
+
+```
+=== Who imports <module>? ===
+Imported by N module(s):
+  ← <module_id> (<path>)
+```
+
+### --impact
+
+```
+=== Impact radius: <file_path> ===
+
+Depends on (this file imports):
+  → <module_id> (<path>)
+
+Depended by (other files import this):
+  ← <module_id> (<path>)
+
+Impact summary: N upstream dependencies, M downstream dependents
+
+# 以下仅在传入 --git-stats 且该文件存在 hotspot/coupling 数据时输出
+Git risk: high (N changes in 90 days)
+Coupled files (co-change):
+  - <peer_path> (coupling: 0.XX, N co-changes)
+```
+
+### --hub-analysis
+
+```
+=== Hub Analysis ===
+
+Top fan-in (most imported by others):
+  1. <module_id> — imported by N module(s)  [<path>]
+
+Top fan-out (imports most others):
+  1. <module_id> — imports N internal module(s)  [<path>]
+```
+
+### --summary
+
+```
+=== Directory Summary ===
+
+<dir>/ (N modules, N classes, N functions, N lines)
+  Key classes: ClassA, ClassB, ...
+  Key imports from: <other_dir>, ...
+```