代码考古学
安装 |
文档 |
维基 |
命令 |
安全模型 |
发布
挖掘技术债务。有信心地恢复。
Code Archaeology 是一个多运行时插件，通过按固定的、测试驱动的探险顺序移除累积的技术沉积物，对代码库进行勘测、编目和安全恢复。它可以在 **OpenCode**（交互式斜杠命令）和 **Hermes Agent**（基于 cron 的后台执行）上运行。
```
+---------------------------------------------------------------+
| CODE ARCHAEOLOGY CAPABILITY PANEL |
+-------------------+-------------------------------------------+
| Default mode | survey: reports only, zero source edits |
| Review mode | excavate: reports plus mock patches |
| Restore mode | applies approved changes with test gates |
| Local state | .archaeology/ runtime artifacts |
| Runtimes | OpenCode plugin + Hermes Agent cron |
| Platforms | macOS/Linux (bash) + Windows (PowerShell) |
| Expedition order | fixed stratigraphy from survey to catalog |
+-------------------+-------------------------------------------+
```
## 功能说明
Code Archaeology 在更改代码之前对仓库进行系统性的挖掘。它对站点进行清点，识别技术债务层，编写可审查的报告，并且仅在 `restore` 模式下应用已批准的更改。
- 对死代码、未使用的导出、不可达函数和过时产物进行编目。
- 在审查后移除遗留的回退方案、已弃用的垫片和兼容层。
- 在提取或类型整合之前绘制循环依赖图。
- 仅在死代码和遗留层移除后才整合重复的类型定义。
- 在不猜测不确定替换的情况下强化弱类型。
- 在保留 I/O 边界的同时发现语义重复和错误处理疏漏。
- 生成保持在工作仓库本地的 `.archaeology/` 报告。
- 同时支持 **OpenCode** 交互式会话和 **Hermes Agent** 基于 cron 的分阶段执行。
## 安装
### OpenCode
将此交接文档粘贴到你的 agent 中：
```
Run `npm pack opencode-code-archaeology@2.2.0`, extract the tarball, then open `package/INSTALL.md` from that archive and follow its instructions.
```
在 `opencode.json` 中推荐安装插件：
```
{
"plugin": [
"opencode-code-archaeology@2.2.0"
]
}
```
全局 npm 安装路径：
```
npm install -g opencode-code-archaeology@2.2.0 && opencode-code-archaeology install && opencode-code-archaeology doctor
```
一次性包运行器路径，如果你的 OpenCode 设置支持通过 Bun 执行包：
```
bunx opencode-code-archaeology@2.2.0 install
bunx opencode-code-archaeology@2.2.0 doctor
```
### Hermes Agent
```
npm install -g opencode-code-archaeology@2.2.0
cd ~/projects/Code-Archaeology
bash hooks/hermes/setup.sh
hermes cronjob create \
--name "code-archaeology-expedition" \
--schedule "every 15m" \
--workdir ~/projects/Code-Archaeology \
--prompt "Run one Code Archaeology expedition phase. Read .archaeology/session.json, execute current phase with verification, advance to next phase."
```
有关先决条件、验证、更新和故障排除，请参阅 [`INSTALL.md`](INSTALL.md)。
## 快速入门
### OpenCode
在要检查的仓库内运行命令系列：
```
/code-archaeology
```
`/code-archaeology` 运行完整的 10 阶段勘测链，无需每阶段提示。它在 `.archaeology/` 下编写报告，不做任何源代码更改。审查报告后，选择是否生成模拟补丁或应用已批准的更改：
```
/code-archaeology-survey
/code-archaeology-excavate
/code-archaeology-restore
```
### Hermes Agent
每次 cron 运行恰好执行一个阶段。运行器读取 `.archaeology/session.json`，使用验证运行当前阶段，然后进入下一阶段：
```
bash hooks/hermes/runner.sh
```
十个阶段在约 2.5 小时内完成（15 分钟间隔）。
## 运行时界面
| 功能 | OpenCode | Hermes Agent |
|---------|----------|--------------|
| 入口 | `/code-archaeology` 斜杠命令 | `cronjob` |
| 阶段 | 一次会话中全部完成 | 每次 cron 运行一个 |
| 验证 | 探险之间 | 每个阶段之间 |
| 回滚 | 手动或自动 | 失败时自动 |
| 状态 | `.archaeology/session.json` | 同一文件 |
| 后台 | 插件保持活跃 | Cron 自动恢复 |
| 实时 | 是 | 延迟（15 分钟间隔） |
## 探险流程
```
flowchart TD
A[Start] --> B[Site Survey and Baseline]
B --> C[Dead Code Excavation]
C --> D[Legacy Stratum Removal]
D --> E[Circular Dependency Cartography]
E --> F[Type Catalog Consolidation]
F --> G[Type Restoration and Hardening]
G --> H[DRY Stratification]
H --> I[Error Handling Stratigraphy]
I --> J[Artifact Cleaning and Documentation]
J --> K[Site Preservation and Final Catalog]
```
## 安全模型
```
flowchart LR
Survey[survey mode] --> Reports[write site reports]
Reports --> Review[human review]
Review --> Excavate[excavate mode: mock patches]
Review --> Restore[restore mode: approved changes]
Restore --> Verify[verify phase]
Verify -->|pass| Next[next expedition]
Verify -->|fail| Revert[revert phase and stop]
```
- `survey` 是默认模式，仅编写报告。
- `restore` 会修改代码，应仅在报告审查后运行。
- `.archaeology/` 是本地运行时状态，不应提交。
- 工作隔离在可配置的分支上，默认为 `refactor/archaeology`。
- 测试和类型检查控制每个恢复阶段。
- 失败的恢复阶段会在下一次探险继续之前回滚。
- I/O 和外部输入边界周围的 try/catch 块永远不会自动移除。
## 命令
### OpenCode
| 命令 | 用途 | 文件更改 |
| --- | --- | --- |
| `/code-archaeology` | 运行完整的 10 阶段勘测链，无需每阶段提示。 | `.archaeology/` 之外无更改。 |
| `/code-archaeology-survey` | 生成站点报告供审查。 | `.archaeology/` 之外无更改。 |
| `/code-archaeology-excavate` | 生成报告和模拟补丁。 | `.archaeology/patches/` 之外无更改。 |
| `/code-archaeology-restore` | 应用已批准的高置信度更改。 | 是，测试驱动。 |
### Hermes Agent
| OpenCode 等价物 | Hermes 机制 | 文件更改 |
| --- | --- | --- |
| `/code-archaeology` | `cronjob` 运行探险循环 | 取决于模式 |
| `/code-archaeology-survey` | `session.json` 中的 `mode = "survey"` | `.archaeology/` 之外无更改 |
| `/code-archaeology-excavate` | `session.json` 中的 `mode = "excavate"` | `.archaeology/patches/` 之外无更改 |
| `/code-archaeology-restore` | `session.json` 中的 `mode = "restore"` | 是，测试驱动 |
## 参数
| 参数 | 默认值 | 描述 | Hermes 说明 |
| --- | --- | --- | --- |
| `repo_path` | `.` | 要挖掘的目标仓库。 | 在首次 cron 运行前在 `session.json` 中设置。 |
| `language` | `typescript` | 用于工具选择的主要语言。 | 相同 |
| `mode` | `survey` | `survey`、`excavate` 或 `restore`。 | 在 `session.json` 中更改以切换模式。 |
| `strict_mode` | `false` | 为 true 时，restore 还可以应用中等置信度的发现。 | 相同 |
| `test_command` | `npm test` | 仅记录会话默认值；验证钩子不执行仓库本地的命令值。使用 `CODE_ARCHAEOLOGY_TEST_COMMAND` 批准当前进程的覆盖。 | 相同 |
| `typecheck_command` | `npx tsc --noEmit` | 仅记录会话默认值；验证钩子不执行仓库本地的命令值。使用 `CODE_ARCHAEOLOGY_TYPECHECK_COMMAND` 批准当前进程的覆盖。 | 相同 |
| `branch_name` | `refactor/archaeology` | 用于隔离恢复工作的分支。 | 相同 |
## 探险顺序
探险顺序是固定的，因为每一层都依赖于之前的挖掘：
1. 站点勘测与基线
2. 死代码挖掘
3. 遗留层移除
4. 循环依赖绘图
5. 类型目录整合
6. 类型恢复与强化
7. DRY 分层
8. 错误处理地层学
9. 产物清理与文档
10. 站点保护与最终编目
不要在死代码和遗留层移除之前整合类型。不要在依赖循环映射之前进行 DRY。
## 语言工具
| 语言 | 死代码 | 依赖 | 类型 | DRY |
| --- | --- | --- | --- | --- |
| TypeScript | `knip` | `madge` | `tsc` | `jscpd` |
| JavaScript | `knip` | `madge` | 不适用 | `jscpd` |
| Python | `vulture` | `pydeps` | `mypy` | `pylint` |
| Go | `deadcode` | `godepgraph` | `go vet` | `golangci-lint` |
| Rust | `cargo-udeps` | `cargo-deps` | `rustc` | `clippy` |
如果缺少首选工具，Code Archaeology 会回退到基于 AST 的手动分析，并将不确定的发现标记为需要人工审查。
## 架构
```
Code-Archaeology/
|-- assets/ # README and repository visual assets
|-- commands/ # OpenCode slash command definitions
|-- dist/ # Built package output for GitHub-based installs
|-- docs/ # Public docs and release notes
|-- hooks/opencode/ # Init, verification, revert, and status hooks
|-- hooks/hermes/ # Setup and runner hooks for Hermes Agent
|-- plugins/ # Repo-local legacy plugin shim
|-- prompts/ # Expedition prompts by phase
|-- schema/ # JSON schemas for reports
|-- skills/ # Code Archaeology skill definitions
| |-- code-archaeology/ # OpenCode skill
| `-- hermes/ # Hermes Agent skill and integration docs
|-- src/ # TypeScript source
|-- INSTALL.md # Multi-runtime install handoff
|-- README.md # Public project overview
`-- AGENTS.md # Agent runtime guide
```
## 运行时产物
所有探险状态都写入目标仓库内的 `.archaeology/`：
| 产物 | 用途 |
| --- | --- |
| `session.json` | 当前探险进度和配置。 |
| `site_survey.md` | 基线清单和地层图。 |
| `expedition1-report.md` 到 `expedition8-report.md` | 每个探险的发现。 |
| `FINAL_CATALOG.md` | 最终挖掘摘要和建议。 |
| `excavation_log.txt` | 应用恢复工作的 `git diff --stat`。 |
| `p/` | `excavate` 模式生成的模拟补丁。 |
| `hermes-runtime.json` | Hermes 运行时配置（仅 Hermes）。 |
## 本地测试
用于插件开发：
```
npm install
npm run build
npm run typecheck
npm pack --json --dry-run
bash -n hooks/opencode/*.sh
bash -n hooks/hermes/*.sh
```
对于恢复探险，在阶段之间运行配置的测试和类型检查命令。捆绑的验证钩子是：
```
# OpenCode
bash hooks/opencode/verify-phase.sh final_verify
# Hermes
bash hooks/hermes/runner.sh
```
## 发布文档
- [`docs/README.md`](docs/README.md) 是文档入口页面。
- [`docs/RELEASE.md`](docs/RELEASE.md) 涵盖发布准备和发布。
- [`INSTALL.md`](INSTALL.md) 是多运行时安装的原始交接文档。
- [GitHub Releases](
标签：AI合规, Hermes Agent, IPv6支持, MITM代理, OpenCode插件, SOC Prime, 代码分析, 代码库健康, 代码恢复, 代码清理, 代码维护, 代码考古, 代码重构, 代码重构工具, 凭证管理, 多运行时, 开发工具, 技术债务, 技术债务管理, 暗色界面, 自定义脚本