技能共享代码库审计

安全 社区

技能解读

当前原文的自动摘译,尚未人工审校。

1. CLI 标志审核

将cmd/skillshare/*.go中定义的每个标志与website/docs/commands/*.md进行比较。报告:未记录:标记存在于代码中,但不存在于文档中 STALE:标记已记录,但在代码中未找到 正常:代码和文档之间的标记匹配

2. 规格与代码

对于specs/中标记为已完成/完成的每个规范:验证源代码中是否存在所描述的功能检查规范的验收标准是否可测试报告:已实施:规范已完成,代码存在

3. 测试覆盖率

对于cmd/skillshare/<cmd>.go中的每个命令处理程序:检查tests/integration/<cmd>_test.go是否存在检查关键行为是否有测试用例报告:已覆盖:命令具有带有测试用例的集成测试文件

4. 目标审核

验证internal/config/targets.yaml条目:每个目标都有global_path和project_path别名一致无重复条目报告:

5. 处理程序拆分审核

对于 cmd/skillshare/<cmd>.go 中超过 300 行的命令,验证是否遵循处理程序拆分约定: 检查大型命令是否正确拆分: 后缀 · 预期大型命令 _handlers.go · 提取的核心逻辑 _render.go · 输出渲染分离

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
安全
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@runkids · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
即装即用
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

Read-only consistency audit across the skillshare codebase. $ARGUMENTS specifies focus area (e.g., "flags", "tests", "targets") or omit for full audit.

**Scope**: This skill only READS and REPORTS. It does not modify any files. Use `implement-feature` to fix issues or `update-docs` to fix documentation gaps.

## Audit Dimensions

Run all 4 dimensions in parallel where possible. For each, produce a summary table.

### 1. CLI Flag Audit

Compare every flag defined in `cmd/skillshare/*.go` against `website/docs/commands/*.md`.

```bash
# Find all flags in Go source
grep -rn 'flag\.\(String\|Bool\|Int\)' cmd/skillshare/
grep -rn 'Args\|Usage' cmd/skillshare/
```

Report:
- **UNDOCUMENTED**: Flag exists in code but not in docs
- **STALE**: Flag documented but not found in code
- **OK**: Flag matches between code and docs

### 2. Spec vs Code

For each spec in `specs/` marked as completed/done:
- Verify the described feature exists in source code
- Check that the spec's acceptance criteria are testable

Report:
- **IMPLEMENTED**: Spec complete, code exists
- **MISMATCH**: Spec says done but code missing or partial
- **PENDING**: Spec not yet marked complete (informational)

### 3. Test Coverage

For each command handler in `cmd/skillshare/<cmd>.go`:
- Check if `tests/integration/<cmd>_test.go` exists
- Check if key behaviors have test cases

```bash
# List all command handlers
ls cmd/skillshare/*.go | grep -v '_test.go\|main.go\|helpers.go\|mode.go'

# List all integration tests
ls tests/integration/*_test.go
```

Report:
- **COVERED**: Command has integration test file with test cases
- **PARTIAL**: Test file exists but missing key scenarios
- **MISSING**: No integration test for this command

### 4. Target Audit

Verify `internal/config/targets.yaml` entries:
- Each target has both `global_path` and `project_path`
- Aliases are consistent
- No duplicate entries

Report:
- **OK**: Target entry complete and valid
- **INCOMPLETE**: Missing required fields
- **DUPLICATE**: Name or alias collision

## Output Format

```
== Skillshare Codebase Audit ==

### CLI Flags (N issues)
| Command   | Flag        | Status       |
|-----------|-------------|--------------|
| install   | --force     | OK           |
| install   | --into      | UNDOCUMENTED |

### Specs (N issues)
| Spec File            | Status      |
|----------------------|-------------|
| copy-sync-mode.md    | IMPLEMENTED |
| some-feature.md      | MISMATCH    |

### Test Coverage (N issues)
| Command   | Status  | Notes              |
|-----------|---------|--------------------|
| sync      | COVERED |                    |
| audit     | PARTIAL | missing edge cases |
| target    | MISSING |                    |

### Targets (N issues)
| Target    | Status     | Notes         |
|-----------|------------|---------------|
| claude    | OK         |               |
| newagent  | INCOMPLETE | no project_path |

== Summary: X OK / Y issues found ==
```

### 5. Handler Split Audit

For commands with >300 lines in `cmd/skillshare/<cmd>.go`, verify the handler split convention is followed:

```bash
# Find large command files
wc -l cmd/skillshare/*.go | sort -rn | head -20
```

Check that large commands are properly split:

| Suffix | Expected for large commands |
|--------|---------------------------|
| `_handlers.go` | Core logic extracted |
| `_render.go` | Output rendering separated |
| `_tui.go` | TUI components isolated |

Report:
- **SPLIT**: Large command properly follows handler split convention
- **MONOLITH**: >300 lines without split (should be refactored)
- **N/A**: Small command, no split needed

### 6. Oplog Coverage

Verify all mutating commands have oplog instrumentation:

```bash
# Find commands that modify state
grep -rn 'func handle\|func cmd' cmd/skillshare/*.go

# Check for oplog.Write calls
grep -rn 'oplog.Write' cmd/skillshare/
```

Mutating commands (install, uninstall, sync, update, init, collect, backup, restore, trash) should all write to oplog. Read-only commands (list, status, check, search, audit, log, version) should not.

Report:
- **INSTRUMENTED**: Mutating command has oplog.Write
- **MISSING**: Mutating command lacks oplog instrumentation
- **N/A**: Read-only command (no oplog expected)

### 7. Web API Consistency

Verify `internal/server/handler_*.go` routes match CLI commands:

```bash
# List all handler files
ls internal/server/handler_*.go | grep -v _test.go

# Check route registration in server.go
grep -n 'HandleFunc\|Handle(' internal/server/server.go
```

Report:
- **SYNCED**: CLI command has corresponding API handler
- **CLI-ONLY**: Command exists in CLI but not in Web API (may be intentional)
- **API-ONLY**: API handler without CLI counterpart (unusual)

## Output Format

```
== Skillshare Codebase Audit ==

### CLI Flags (N issues)
| Command   | Flag        | Status       |
|-----------|-------------|--------------|
| install   | --force     | OK           |
| install   | --into      | UNDOCUMENTED |

### Specs (N issues)
| Spec File            | Status      |
|----------------------|-------------|
| copy-sync-mode.md    | IMPLEMENTED |
| some-feature.md      | MISMATCH    |

### Test Coverage (N issues)
| Command   | Status  | Notes              |
|-----------|---------|--------------------|
| sync      | COVERED |                    |
| audit     | PARTIAL | missing edge cases |
| target    | MISSING |                    |

### Targets (N issues)
| Target    | Status     | Notes         |
|-----------|------------|---------------|
| claude    | OK         |               |
| newagent  | INCOMPLETE | no project_path |

### Handler Split (N issues)
| Command   | Lines | Status    | Notes              |
|-----------|-------|-----------|--------------------|
| install   | 450   | SPLIT     | 6 sub-files        |
| audit     | 320   | MONOLITH  | should split render |
| status    | 80    | N/A       |                    |

### Oplog (N issues)
| Command   | Mutating? | Status        |
|-----------|-----------|---------------|
| install   | Yes       | INSTRUMENTED  |
| trash     | Yes       | MISSING       |
| list      | No        | N/A           |

### Web API (N issues)
| Command   | CLI | API | Status   |
|-----------|-----|-----|----------|
| install   | Yes | Yes | SYNCED   |
| diff      | Yes | No  | CLI-ONLY |

== Summary: X OK / Y issues found ==
```

## Rules

- **Read-only** — never modify files, only report
- **Evidence-based** — every finding must include file path and line number
- **No false positives** — verify with grep before flagging
- **Scope $ARGUMENTS** — if user specifies "flags", only run dimension 1; "handlers" for dimension 5, "oplog" for dimension 6, "api" for dimension 7

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。