输出与目录标准（claude-code-qiwei-assistant）

本文件定义技能包所有生成文件的目录规则。任何工具、脚本或 Skill 生成文件时必须遵循本标准，并通过 mcp/src/core/output-paths.js 模块解析路径，禁止直接拼 process.cwd() + 'outputs'。

1. 顶层目录职责

claude-code-qiwei-assistant/
├── bin/          # CLI 入口，不生成文件
├── mcp/          # MCP 服务源码与接口清单（catalog 为构建产物，由 scripts/build-catalog.py 生成）
├── skills/       # SKILL.md 定义，只读
├── scripts/      # 构建 / 安装 / 冒烟脚本
├── docs/         # 人工与生成文档（见第 4 节）
└── outputs/      # 所有运行期生成文件（见第 2 节，git 忽略）

2. /outputs 生成规则

统一根目录：<包根>/outputs，可用环境变量 QIWEI_OUTPUTS_DIR 覆盖。目录不存在时由 output-paths.js 自动创建。

第一层为固定类别，禁止在 outputs 根目录直接放文件：

类别	用途
`login/`	扫码登录二维码与预览页（保持固定文件名，最新一次覆盖）
`api-calls/`	`qiwei_api_call` 落盘的请求/响应样本
`subscription/`	订阅、席位、余额查询快照
`meetings/`	官方 CLI 会议相关导出
`docs/`	官方 CLI 文档能力导出
`messages/`	消息发送记录与回执
`smoke/`	冒烟测试产物
`tmp/`	临时文件，可随时清理

2.1 两种落盘模式

latest 模式（固定文件名，覆盖写）：适用于"只关心最新一份"的文件，如登录二维码。路径：outputs/<类别>/<固定文件名>，通过 latestPath(category, filename) 获取。
run 模式（按次归档）：适用于每次运行都要保留的产物。路径：outputs/<类别>/<YYYY-MM-DD>/<HHmmss>-<slug>/，通过 createRunDir(category, slug) 创建。每个 run 目录必须包含 manifest.json（用 writeRunManifest(runDir, meta) 生成），至少含：
```
{
"createdAt": "2026-07-12T09:00:00.000Z",
"tool": "qiwei_official_call",
"summary": {},
"files": ["meeting-list.json"]
}
```

2.2 命名规则

目录与文件名一律小写 kebab-case；slug 由 slugify() 生成，最长 60 字符。
日期用 YYYY-MM-DD，时间用 HHmmss（UTC）。
禁止绝对路径、空格和平台保留字符。

2.3 保留与清理

tmp/ 可随时删除；其余类别按日期目录归档，建议保留最近 30 天。
outputs/ 整体在 .gitignore 中，不入库。

3. 输出模块 API

mcp/src/core/output-paths.js 暴露：

outputsRoot()                       // outputs 根目录（含 QIWEI_OUTPUTS_DIR 覆盖）
categoryDir(category)               // 确保并返回类别目录
latestPath(category, filename)      // latest 模式路径
createRunDir(category, slug, date?) // run 模式目录
writeRunManifest(runDir, manifest)  // 写 manifest.json
slugify(value) / dateStamp() / timeStamp()
OUTPUT_CATEGORIES                   // 允许的类别列表

新增输出类别时：先在 OUTPUT_CATEGORIES 注册，再更新本文件第 2 节表格。

4. /docs 生成规则

docs/
├── OUTPUT-STANDARD.md   # 本标准
├── specs/               # 设计与需求规格（人工撰写，kebab-case.md）
├── guides/              # 使用指南、课程讲义
└── generated/           # 脚本生成的文档，文件头必须注明生成脚本与时间，不手工编辑

生成型文档只能写入 docs/generated/，并以 <主题>-<YYYY-MM-DD>.md 命名；
运行期数据（JSON 快照、日志、二维码等）一律进 outputs/，不得写入 docs/；
docs/ 入库（git 跟踪），outputs/ 不入库。

5. 校验

运行 npm run outputs:validate（scripts/validate-output-standard.js）检查：

outputs 第一层只包含注册类别；
run 模式目录包含 manifest.json；
docs 第一层只包含本节列出的文件与目录。

npm run check 已包含上述脚本的语法检查。

OUTPUT-STANDARD.md 4.1 KB История Исходник