القائمة
对后端源码文件生成严格遵循模板的分析文档。读源码→提取结构→按模板填充所有章节（职责/行为意图/行为/约束/输入输出/调用链/副作用/异常处理/PRD映射）。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use this skill when the input is product/business narrative and the goal is to produce executable domain modeling artifacts before YAML coding. It converts descriptions into model cards (context, aggregate, relations, state machine, validation, actions, events, custom overlays), enforces single-writer/cross-domain event rules, creates refine task lists, and prepares handoff inputs for `ubo-yaml-writing`.
为复杂需求生成父 issue + sub-issues 的 DAG 化写作模板与创建步骤，默认使用 Sub-Issue 模式（parent/depends-on），并提供降低并行冲突的拆分规则。
使用 taskctl research 工具进行假设驱动的研究推理。声明假设、收集证据、贝叶斯更新后验概率，最终收敛到可行动的结论。
为复杂需求生成父 issue + sub-issues 的 DAG 化写作模板与创建步骤，默认使用 Sub-Issue 模式（parent/depends-on），并提供降低并行冲突的拆分规则。
根据 niuma 工作流要求，创建结构化的 GitHub Issue，便于后续 AI 自动化处理
为 bcc arch 命令创建和维护 seed 文件。分析代码结构，定义模块边界，识别依赖关系，避免漏定义和过度定义。
| name | backend-file-analysis |
| description | 对后端源码文件生成严格遵循模板的分析文档。读源码→提取结构→按模板填充所有章节（职责/行为意图/行为/约束/输入输出/调用链/副作用/异常处理/PRD映射）。 |
| allowed-tools | Read, Grep, Glob, Bash, Write, Edit |
| user-invocable | true |
backend-file-analysis/
├── SKILL.md # 本文件（执行指南）
├── template.md # 分析文档模板（严格遵守，所有章节必填）
└── extraction-rules.md # 各语言提取规则参考
对指定的后端源码文件，生成严格遵循模板的分析文档。文档路径与源文件一一对应：docs/backend-trace/files/<源文件相对路径>.md。
/backend-file-analysis <源文件路径或目录> [--project-root <项目根目录>] [--docs-dir <文档输出目录>]
示例：
/backend-file-analysis src/gateway/router.ts
/backend-file-analysis lib/shop/order/
/backend-file-analysis app/controllers/ShopController.php --project-root ~/document/upfit
每个文件的分析文档必须包含以下 全部 10 个章节，顺序固定：
# <源文件相对路径>
## 职责
- 一句话描述核心功能边界、上下游角色。
## 行为意图
- 该文件存在的目的（为什么要做这件事，输入语义/业务触发）
- 与上层能力的关系（如 Gateway/agent/cron/频道/插件/infra 等）
## 行为
- 关键流程（按步骤、时序、分支）
- 对输入的处理策略（参数校验、分发、持久化、失败路径）
## 约束
- 约束条件（权限、环境、依赖、配置前置）
- 失败边界（超时、重试、幂等、降级）
- 安全边界（认证、授权、越权防护、执行审批）
## 输入输出
- 输入对象（必填/可选字段）
- 输出对象（返回值、事件、回调、持久化副作用）
## 调用链位置
- 上游调用者（谁会调用它）
- 下游依赖（调用了哪些内部文件）
### 本地依赖（下游）
- 列出关键依赖文件
### 上游引用
- 列出直接调用方
## 状态与副作用
- FS 读写
- 网络/进程调用
- 事件发布/订阅
- 日志与审计
## 异常处理
- 异常来源（参数错误、权限失败、超时、外部服务异常）
- 处理策略（重试/返回错误码/补偿）
## 与 PRD 需求映射
- 关联 PRD 标签（如 `gateway-routing`、`agent-runtime`、`session-management`）
## 溯源证据
- `source: <源文件路径>`
- 证据时间：`YYYY-MM-DD`
- 关键代码定位（函数名 / 常量 / 分支）
.ex/.exs → Elixir，.go → Go，.rs → Rust，.php → PHP，.ts/.tsx → TypeScript对每个源码文件，执行以下提取：
a) 结构提取（确定性，直接从代码读取）
| 提取项 | Elixir | Go | Rust | PHP | TypeScript |
|---|---|---|---|---|---|
| 公开函数 | def | 大写开头 | pub fn | public function | export function/class |
| 类型签名 | @spec | 函数签名 | 返回类型 | PHPDoc | TS 类型标注 |
| 错误模式 | {:error, _} | error 返回 | Result::Err | throw | throw/reject |
| 模块调用 | Mod.func() | pkg.Func() | crate::func() | Class::method() | import from |
| 模块文档 | @moduledoc | // Package | //! doc | /** */ | JSDoc |
| 副作用 | GenServer/Task/HTTP | goroutine/net | async/tokio | curl/file | async/fetch/fs |
b) 语义分析（需要理解代码逻辑）
对每个文件，搜索项目中哪些文件引用了它：
grep 搜索 alias ModuleName 或 ModuleName.funcgrep 搜索 import "pkg/path" 或 pkg.Funcgrep 搜索 from './path' 或 require('./path')grep 搜索 use ClassName 或 ClassName::<docs-dir>/files/<源文件相对路径>.md（待补充：<原因>） 而非留空生成后自检：
处理目录时，先输出文件清单和进度，逐个生成：
扫描: src/gateway/ → 12 个源文件
[1/12] src/gateway/router.ts → docs/backend-trace/files/src/gateway/router.ts.md ✓
[2/12] src/gateway/middleware.ts → docs/backend-trace/files/src/gateway/middleware.ts.md ✓
...
完成: 12/12，全部章节齐全
（项目无 PRD 文档，跳过映射）