审计文件
- 作者仓库星标 45
- 许可证 BSD-2-Clause
- 作者仓库 leos_claude_starter
- 领域
- 安全
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 94 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @leogodin217 · BSD-2-Clause
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
docs/audits/
YYYY-MM-DD_HHMMSS/
manifest.yaml # checkpoint state
summary.md # generated after all audits complete
findings/
actors.md
behaviors.md
...
# Audit Docs
Orchestrate sequential documentation audits with file-based checkpointing. Enables resumption across sessions.
## Output Location
```
docs/audits/
YYYY-MM-DD_HHMMSS/
manifest.yaml # checkpoint state
summary.md # generated after all audits complete
findings/
actors.md
behaviors.md
...
```
## Process
### 1. Check for Incomplete Session
Look for existing sessions:
```
Glob: docs/audits/*/manifest.yaml
```
For each manifest found, read it. If any has `status: auditing` or `status: summarizing`:
```
AskUserQuestion:
question: "Found incomplete audit session from {session_id}. How should I proceed?"
options:
- "Resume the incomplete session"
- "Start a fresh audit (abandons previous)"
```
If "Resume" → skip to Phase 2 or 3 based on manifest status.
If "Start fresh" → continue to initialization.
If no incomplete sessions found, proceed to initialization.
### 2. Initialize Session
Create session folder:
```
session_id = current timestamp as "YYYY-MM-DD_HHMMSS"
folder = docs/audits/{session_id}/
```
Create the folder structure:
```
docs/audits/{session_id}/
docs/audits/{session_id}/findings/
```
Discover architecture docs:
```
Glob: docs/architecture/*.md
```
**Exclude:**
- `README.md` (index/navigation)
- `PROCESS.md` (workflow documentation)
Write initial manifest:
```yaml
session_id: "{session_id}"
created_at: "{ISO timestamp}"
status: "auditing"
docs:
- name: "actors.md"
path: "docs/architecture/actors.md"
status: "pending"
error: null
- name: "behaviors.md"
path: "docs/architecture/behaviors.md"
status: "pending"
error: null
# ... all discovered docs
```
Report: "Created audit session {session_id} with {N} docs to audit."
### 3. Audit Phase (Sequential, Checkpointed)
Read manifest to find docs with `status: pending`.
For each pending doc, **one at a time**:
1. **Update manifest** - set doc `status: "auditing"`
2. **Launch doc-auditor agent** (NOT in background):
```
Task(
subagent_type="doc-auditor",
prompt="Audit this architecture doc against implementation.\n\ndoc_path: {doc_path}",
run_in_background=false
)
```
3. **Write findings file** - take agent response and write to `findings/{doc_name}`:
```markdown
# Audit: {doc_name}
**Audited:** {ISO timestamp}
**Doc path:** {doc_path}
## Findings
{findings from agent, numbered list}
## Verified Accurate
{verified items from agent, bullet list}
```
4. **Update manifest** - set doc `status: "complete"`
5. **Report progress**: "Completed {n}/{total}: {doc_name} - {X} findings"
6. **Continue to next pending doc**
**If agent returns error:** Set doc `status: "error"`, `error: "{message}"`, continue to next doc.
**Checkpoint guarantee:** After each doc, manifest reflects current state. If context exhausts, next session resumes from manifest.
### 4. Summary Phase
Once all docs have `status: complete` or `status: error`:
1. **Update manifest** - set `status: "summarizing"`
2. **Read all findings files** from `findings/` folder
3. **Generate summary.md**:
```markdown
# Documentation Audit Summary
**Session:** {session_id}
**Completed:** {ISO timestamp}
## Overview
- Docs audited: {total}
- Docs with findings: {count with findings}
- Docs verified accurate: {count with no findings}
- Docs with errors: {count with errors}
## Findings
### {doc_name}
{copy findings section from that doc's file}
### {doc_name}
...
## Verified Accurate
- {doc_name}
- {doc_name}
- ...
## Errors
- {doc_name}: {error message}
- ...
```
4. **Update manifest** - set `status: "complete"`
5. **Report**: "Audit complete. Summary written to docs/audits/{session_id}/summary.md"
### 5. Present and Ask for Approval
Display the summary to the user (read and output summary.md content).
Then ask:
```
AskUserQuestion:
question: "How should I proceed with documentation updates?"
options:
- "Fix all findings"
- "Show me the specific changes first"
- "Skip updates for now"
```
### 6. Apply Fixes (If Approved)
For each finding to fix:
1. Read the doc
2. Locate the incorrect section
3. Edit to match implementation
4. Follow "Code Is Truth" principle:
- Prune duplicated details (link to code instead)
- Keep rationale and invariants
- Remove stale content
Report each change made.
### 7. Verification (Optional)
After fixes, offer to re-run audit on modified docs only:
```
AskUserQuestion:
question: "Want me to verify the fixes?"
options:
- "Yes, re-audit modified docs"
- "No, I'll review manually"
```
---
## Manifest Schema
```yaml
session_id: str # "YYYY-MM-DD_HHMMSS"
created_at: str # ISO 8601 timestamp
status: str # "auditing" | "summarizing" | "complete"
docs:
- name: str # "actors.md"
path: str # "docs/architecture/actors.md"
status: str # "pending" | "auditing" | "complete" | "error"
error: str | null # error message if status=error
```
---
## Findings File Format
```markdown
# Audit: {doc_name}
**Audited:** {ISO timestamp}
**Doc path:** {path}
## Findings
1. **{title}**
- Doc says: "{quote from doc}"
- Code does: {actual behavior}
- Location: {file}:{line}
2. **{title}**
...
## Verified Accurate
- {item verified correct}
- {item verified correct}
```
---
## Doc-to-Code Mapping
The doc-auditor agent discovers code paths from within the doc itself:
1. **Explicit references:** Look for `src/fabulexa/...` paths in the doc
2. **Code References section:** Many docs have a table linking topics to files
3. **Naming convention:** `{name}.md` often maps to `src/fabulexa/{name}/`
The agent should NOT rely on a hardcoded mapping.
---
## Example: Fresh Run
```
User: /audit-docs
Claude: Checking for incomplete sessions...
No incomplete sessions found.
Creating audit session 2025-01-21_143022 with 10 docs to audit.
Auditing actors.md...
Completed 1/10: actors.md - 2 findings
Auditing behaviors.md...
Completed 2/10: behaviors.md - 0 findings
...
Audit complete. Summary written to docs/audits/2025-01-21_143022/summary.md
# Documentation Audit Summary
...
How should I proceed with documentation updates?
[Fix all findings] [Show changes first] [Skip updates]
```
## Example: Resume After Context Exhaustion
```
User: /audit-docs
Claude: Checking for incomplete sessions...
Found incomplete audit session from 2025-01-21_143022.
Progress: 6/10 docs complete.
How should I proceed?
[Resume the incomplete session] [Start a fresh audit]
User: Resume
Claude: Resuming session 2025-01-21_143022...
Auditing simulation.md...
Completed 7/10: simulation.md - 1 finding
...
```
章节与文件索引
按说明文件中的顺序排列。
1. 检查是否有未完成的会话
2. 初始化会话
3. 审计阶段(顺序、检查点)
4.总结阶段
5. 出席并请求批准
文件/命令 -> status: auditing · status: summarizing · README.md · PROCESS.md · status: pending · status: "auditing" · findings/{doc_name} · status: "complete"
内容校验值 -> d672200e82db
当前原文的自动摘译,尚未人工审校。
1. 检查是否有未完成的会话
查找现有会话:对于找到的每个清单,阅读它。如果有
status: auditing或status: summarizing:如果“恢复”→根据清单状态跳至阶段2或3。如果“Start fresh”→继续初始化。如果没有发现不完整的会话,则继续初始化。2. 初始化会话
创建会话文件夹:创建文件夹结构:发现架构文档:排除:
README.md(索引/导航)3. 审计阶段(顺序、检查点)
阅读清单以查找包含
status: pending的文档。对于每个待处理的文档,一次一个:更新清单 - 设置文档status: "auditing"启动文档审核代理(不在后台):写入结果文件 - 获取代理响应并写入findings/{doc_name}:4.总结阶段
一旦所有文档都有
status: complete或status: error:更新清单 - 设置status: "summarizing"从findings/文件夹中读取所有结果文件生成summary.md:更新清单 - 设置status: "complete"5. 出席并请求批准
向用户显示摘要(读取并输出summary.md内容)。然后问: