ArmorBreak · 破甲模式

DeepSeek Harness 原生「授权逆向工程与安全研究」Agent 模式：46 个真实可执行的离线分析能力、L0–L3 代码级权限引擎、逐任务证据哈希链与可复核报告。以 Cordis Bundle + Agent preset 形式嵌入 DeepSeek Harness，不修改 Harness 核心。

Authorized Reverse Engineering & Security Research Agent — a native Agent preset for DeepSeek Harness / Cordis.

Slogan：Evidence or it didn't happen. 每一个安全结论，都必须能回到证据。

徽章说明：不展示未接入的服务指标（Docker 拉取量、第三方生态评分等）；测试数/覆盖率来自本仓库可复现的 node --test 结果，CI 徽章以 GitHub Actions 实际运行为准。

目录

• 一、项目概览 Overview
• 二、设计哲学与原则 Design Philosophy
• 三、核心架构 Core Architecture
• 四、核心技术原理 Technical Principles
• 五、安全设计 Security
• 六、关键特性 Key Features
• 七、技术栈 Tech Stack
• 八、性能基准 Benchmarks
• 九、快速开始 Quick Start
• 十、安装与部署 Installation
• 十一、使用指南 Usage
• 十二、治理与社区 Governance
• 十三、路线图 Roadmap
• 十四、架构决策记录 ADR
• 十五、故障排查与 FAQ
• 十六、生态与集成 Ecosystem
• 十七、案例研究 Case Studies
• 十八、许可证 License
• 十九、致谢 Acknowledgments
• 附录：文件结构与文档索引

一、项目概览 Overview

1.1 背景与痛点

安全研究 Agent 在 2024–2026 年快速从「调用几个工具的聊天机器人」演进为「带规划与执行闭环的智能体」。但把它真正放进授权研究现场时，四类结构性缺陷会立刻暴露：

技术层面，DSH/Cordis 生态提供了原生扩展点（bundle patch、Agent preset、工具/技能注册、审批服务），但缺少一个把「专业能力 + 权限 + 证据」组合起来的参考实现。 工程层面，安全分析工具链普遍重依赖（JVM/原生库/规则包），在受限主机和宿主进程内不可移植。 业务层面，授权研究者需要的是可复核的结论，而不是更大声的告警；违反授权范围的自动化哪怕只有一次，也会让研究失去合法性。

ArmorBreak 的设计目标因此不是「再加一个安全 AI」，而是：

把授权边界、真实执行、证据链、可复核报告，做成 DeepSeek Harness 里一个可安装、可卸载、可审计的 Agent 模式。

1.2 项目定位

1.3 核心价值（全部可量化）

1.4 可视化展示

① 模式状态面板（真实截图，注册在 conversation.composer.dock，读取只读路由 /armorbreak/state）：

② 报告交付物（同一模式下多任务、多格式产出，文件名即工作流+时间戳）：

③ 架构全景（数据流见 §三）：

                 ┌──────────────────────── DeepSeek Harness Host ────────────────────────┐
                 │  Loader composition: dsh-base → dsh-web-app → [dsh-armorbreak layer]  │
                 │                                                                        │
  Agent preset ──┼─► 破甲模式 (persona)                                                   │
  「破甲模式」    │      ├─ 8 model-facing tools  (armorbreak_*)                            │
                 │      ├─ 7 bundled skills      (ctx.skills.register)                    │
                 │      └─ standard fs/shell/compaction tooling                            │
                 │                                                                        │
                 │  Host row: armorbreak ──► 运行时单例                                     │
                 │     ├─ Capability Registry (46, contract-validated)                     │
                 │     ├─ Scope Policy (L0–L3, approvals, allowlists, rate limit)          │
                 │     ├─ Execution Runner (bounded I/O, timeout, evidence, audit)         │
                 │     ├─ Task Engine (15 states, 9 workflows)                             │
                 │     ├─ Evidence/Audit hash chains (.armorbreak/)                        │
                 │     └─ GET /armorbreak/state (read-only, redacted) ──► browser card     │
                 └────────────────────────────────────────────────────────────────────────┘

二、设计哲学与原则 Design Philosophy

2.1 核心设计理念

1. Fail-closed（默认拒绝）：没有授权就没有网络，没有审批就没有动态执行，L3 永远拒绝。
2. Evidence-first（证据优先）：任务不是一个聊天回合，而是一份可复核的工件：状态轨迹、步骤结果、证据哈希链、审计哈希链。
3. Zero-dependency（零依赖可移植）：模式必须能在任意 DSH 主机上安装即用；能力实现只使用 Node 标准库。
4. Additive extension（增量扩展）：只 insert 自己的行与 preset，不覆盖、不重构 Harness 核心；卸载后既有模式完整保留。
5. Untrusted-by-default（被分析内容不可信）：样本、日志、PCAP payload、源码注释中的「指令」一律视为数据，不改变任务/范围/安全规则。
6. Honest verification（诚实的验证等级）：observed / corroborated / hypothesis / unverified 四级；扫描告警永远不自动升级为确认漏洞。

2.2 核心设计准则（6 条，含工程落地）

2.3 技术选型与 Trade-off

三、核心架构 Core Architecture

3.1 分层架构

3.2 核心数据流（一次真实分析的生命周期）

sequenceDiagram
    autonumber
    participant U as Operator / Model
    participant T as Tool (armorbreak_analyze/workflow)
    participant R as ExecutionRunner
    participant P as ScopePolicy
    participant A as ApprovalService
    participant C as Capability
    participant E as EvidenceStore
    participant D as AuditLog
    participant F as Files (.armorbreak)

    U->>T: capability + target + workspace
    T->>R: runCapability(task, capabilityId, ...)
    R->>R: prepareTask: CREATED→SCOPE_VALIDATION→ENVIRONMENT_CHECK→PLANNING
    alt L0 offline
        R->>P: checkFile(realpath containment)
    else L1 dynamic
        R->>P: checkExecution(isolation available?)
        R->>A: request(allowed-once)
        A-->>R: grant / reject
    else L2 active
        R->>P: checkNetwork(target, authorization, approval, rate)
    else L3
        R-->>T: PolicyDenied(L3_DENIED)
    end
    R->>C: run(boundedInput)
    C-->>R: {summary, data, findings, evidence}
    R->>E: appendEvidence (SHA-256 + hash chain)
    R->>E: addFinding (fingerprint dedupe)
    R->>D: append capability.run.start/end (redacted)
    R->>F: atomic writes
    R-->>T: normalized result
    T-->>U: bounded Markdown + structured data
    Note over R,F: finalize: VERIFYING→REPORTING→COMPLETED/PARTIAL_SUCCESS

异常路径：策略拒绝 → 任务 REJECTED（不执行）；能力抛错 → 步骤 FAILED，其余独立步骤继续， 最终 PARTIAL_SUCCESS 且证据保留；超时/取消 → TIMED_OUT / CANCELLED。

3.3 核心模块拆解

3.4 关键时序：审批与拒绝

flowchart TD
    A[工具调用 L1/L2 能力] --> B{审批服务可用?}
    B -- 否 --> R1[FAIL CLOSED: APPROVAL_REJECTED]
    B -- 是 --> C[ctx.approval.request]
    C --> D{outcome == allowed-once?}
    D -- 否 --> R1
    D -- 是 --> E[ScopePolicy.recordApproval]
    E --> F{scope 校验通过?}
    F -- 否 --> R2[PolicyDenied: OUT_OF_SCOPE / APPROVAL_MISMATCH]
    F -- 是 --> G[consume approval + rate token]
    G --> H[execute capability]

四、核心技术原理 Technical Principles

4.1 创新点总览

4.2 策略引擎的代数模型

风险格：能力风险 r ∈ {L0, L1, L2, L3}，任务风险取步骤最大值：

riskMax = max_{s ∈ steps} risk(capability(s))        // L0 < L1 < L2 < L3

执行许可（allow(task, cap)）：

allow = 
  (r = L0) ∧ (pathAllowed(target) ∨ authorizedPath(target))
∨ (r = L1) ∧ isolationAvailable ∧ approvalGranted(task, target) ∧ pathAllowed(sample)
∨ (r = L2) ∧ authorizedNetwork(target) ∧ approvalGranted(task, target) ∧ rateToken(target)
∨ false                                    // r = L3 恒 false

路径约束（防符号链接/目录穿越）：

resolved = realpath(target exists ? target : resolve(target))
allowedPath ⇔ inside(realpath(workspace), resolved) ∨ ∃ a ∈ authorizations: inside(realpath(a.path), resolved)
denySensitive(resolved) ⇔ resolved ∈ {System32, SysWOW64, /proc, /sys, /dev, /etc/shadow, …}

网络匹配支持精确主机、*.domain、IPv4/IPv6 CIDR、可选端口；端口作用域模式不匹配端口未知的目标：

match(pattern, target) =
  portOK(pattern.ports, target.port)
  ∧ ( target ∈ CIDR(pattern)                      if pattern is CIDR
      ∨ target.host = pattern.host                 if exact
      ∨ target.host endswith "." + pattern.domain  if "*.domain" )
portOK(ports, p) = ports = ∅ ∨ (p ≠ null ∧ p ∈ ports)

令牌桶限速（每 host，容量 20，补充 0.5 token/s）：

tokens(t) = min(C, tokens(t₋₁) + elapsed × ρ)
allow = tokens ≥ 1; tokens -= 1

4.3 哈希链结构

审计与证据都是追加 JSONL；第 n 条记录：

record_n = { seq:n, at, prevHash: hash_{n-1}, payload }
hash_n   = SHA256(prevHash + "\n" + canonicalJSON(record_n \ {hash}))

verify: ∀n: record_n.prevHash = hash_{n-1} ∧ SHA256(...) = hash_n

canonicalJSON 对对象键排序，避免序列化差异导致误判。并发安全由按文件互斥队列保证：

mutex(file):  tail = prior.then(() => gate)
append:       await prior; tail' = readTail + compute + write; release

4.4 无损 JSON 净化（Tool Output Contract）

Harness 的审计通道只接受无损 JSON。工具输出在出口执行深度投影：

toLosslessJson(value):
  null | string | finite number | boolean | array | plain object → 保留
  function | symbol | undefined → 丢弃
  bigint → decimal string
  Date → ISO string
  TypedArray → { type:'bytes', length }
  cycle → "[circular]";   depth > 12 → "[depth-limit]"

该函数由 tests/tools-lossless.test.mjs 递归验证；它也是真实故障（value is not lossless JSON）的修复产物。

4.5 有界解析与复杂度

4.6 性能优化（含实测收益）

已知性能瓶颈（诚实记录）：一次完整的 runner 调用约 36 ms，其中解析仅 0.8 ms， 其余是任务状态/证据/审计的持久化。批量场景应复用任务而非每样本建任务（路线图 R1）。

4.7 高可用与一致性（单进程语义）

ArmorBreak 不是分布式服务；它的一致性模型是单 Host 进程内的顺序持久化：

• 任务状态机非法迁移直接抛错，不会产生「不可能状态」；
• 证据/审计链只追加，篡改可检测；链损坏会在报告与工具结果中显著标注；
• 原子写保证崩溃后文件要么是旧版要么是新版；
• 进程内互斥保证并发工具调用不 fork 链；
• 不支持多 Host 进程同时写同一工作区（未加跨进程文件锁）；已知限制见 docs/known-issues.md。

五、安全设计 Security

5.1 威胁模型

5.2 纵深防御体系

1. 身份层：mode 选择 + persona 硬边界（但边界执行不依赖它）。
2. 策略层：ScopePolicy 路径/网络/审批/限速。
3. 执行层：ExecutionRunner 单一咽喉；能力无法绕过 runner 获得输入。
4. 数据层：有界读取、输出截断、脱敏、哈希链、原子写。
5. 展示层：只读路由 + 脱敏快照；不提供任何执行入口。
6. 宿主层（委托）：DSH 自身的 sandbox/approval/persistence；ArmorBreak 不替代宿主沙箱。

5.3 安全审计与合规

• 代码审计：node --test（146 用例）覆盖策略允许/拒绝、路径逃逸、并发链、脱敏、YAML 原型污染；
• 依赖漏洞：零运行时依赖，无第三方供应链面；
• 数据合规：全部数据留在本机工作区，不上传；报告可导出；
• 参考标准映射：OWASP ASVS（输入校验/访问控制/日志）、CWE 映射、CVSS 4.0 评分依据、SARIF 2.1.0 输出； 不宣称通过等保/GDPR/SOC2 认证（本地工具，无云服务）。

5.4 漏洞披露

见 SECURITY.md：GitHub 私密安全公告或邮件；72h 确认、7 天分诊、高危 30 天内修复计划、默认 90 天协调披露；致谢机制。

六、关键特性 Key Features

6.1 基础能力层（离线、零依赖）

# 例：单能力执行（模型工具调用）
armorbreak_analyze {
  "capability": "binary.identify",
  "target": "D:\\work\\sample.exe",
  "workspace": "D:\\work"
}

6.2 高级能力层（差异化）

• 9 个工作流：BinaryStaticAnalysis、AndroidAPKReview、WebCodeSecurityReview、 PCAPInvestigation、DependencyAudit、CTFArtifactAnalysis、ForensicFileReview、 WebAPIReview、SecurityReportGeneration。
• 15 状态任务机：规划期 target-kind 校验、失败保留、部分成功、取消/超时。
• 证据/审计双哈希链：报告自动附带链校验结果。
• 授权 + 平台审批：真实 ctx.approval.request 桥接，无通道 fail-closed。
• 状态卡：宿主 Web UI 内展示能力/隔离/最近任务（只读、脱敏）。

armorbreak_workflow action=start workflow=WebCodeSecurityReview \
  target="D:\\repo" workspace="D:\\work"
→ plan: 4 steps (sast.scan/secrets/deps/sbom), targetKind=directory
armorbreak_workflow action=run taskId=task_...
→ 4/4 DONE, evidence N, findings M, report path

6.3 企业级特性（可运维、可审计）

6.4 生态扩展能力

• DSH 生态：作为 Cordis Bundle / Agent preset 注册，见 docs/marketplace.md。
• 外部工具适配：探测 + 安装指引（当前版本）；适配器接口已在契约中预留。
• UI 扩展：dsh.client + Slot 注册；可继续扩展任务工作台/工具中心。
• 报告互操作：SARIF 2.1.0（CI/代码扫描平台）、CycloneDX SBOM、Markdown/HTML/JSON。

七、技术栈 Tech Stack

八、性能基准 Benchmarks

完整方法、环境与复现命令见 docs/benchmarks.md；原始数据 benchmarks/results.json。

8.1 测试环境

Intel Core Ultra 9 290HX Plus（24C/24T，2.70 GHz）· 63.68 GiB RAM · Windows 11 x64 · Node v24.16.0 · ArmorBreak v1.0.3（39 capabilities / 8 domains）· 样本 notepad.exe 360,448 B · 合成 PCAP 5,000 包/700,024 B · 合成 JS 项目 200 文件。

8.2 核心结果（p50，parser 级）

8.3 端到端与报告

8.4 横向与纵向对比

• 横向：本机未安装 Ghidra/Semgrep/TShark 等外部工具，因此只做架构维度定性对比（依赖、离线默认、证据链、策略、可移植性），不伪造性能数字；见 benchmarks 文档 §5。
• 纵向：v1.0.0 → v1.0.3 测试 128→146，核心覆盖率 84.9%→85.6%，runner 覆盖率 88.55%→93.65%，并发互斥引入的额外开销为每次 append 一次 promise 队列（µs 级，低于文件 I/O 抖动）。

8.5 复现

node benchmarks/bench.mjs --sample /path/to/sample.exe --out benchmarks/results.json
node --test --experimental-test-coverage

九、快速开始 Quick Start

9.1 环境要求

• DeepSeek Harness Desktop 0.2.1-rc.2（或同版本 CLI profile）；Node 24 随 Harness 提供。
• 本机文件系统可写（任务数据写在工作区 .armorbreak/）。
• 可选：Docker（L1）、LibreOffice（PDF）、外部安全工具（增强）。

9.2 一分钟安装（Desktop）

git clone https://github.com/LYL-Z/dsh-armorbreak.git D:\tools\dsh-armorbreak
# 打开 DeepSeek Harness → 设置 → 插件 → 添加插件 → 选择 D:\tools\dsh-armorbreak
# 或让 Agent 执行：plugin_manager action=install_bundle target="D:\\tools\\dsh-armorbreak"

新建会话 → 模式选择 → 破甲模式。输入框下方会出现状态卡。

9.3 第一个分析

调用 armorbreak_health 检查环境；
然后创建任务并用 BinaryStaticAnalysis 工作流分析 D:\samples\hello.exe；
最后生成 markdown 报告并汇报：任务 id、状态、证据数、发现数、报告路径。

预期（真实输出形状）：

任务 task_xxx → COMPLETED；证据 ≥7；发现 ≥0；
报告：D:\work\.armorbreak\tasks\task_xxx\reports\binarystaticanalysis_<ts>.md

9.4 常见启动问题

十、安装与部署 Installation & Deployment

10.1 多形态安装

为什么没有 Docker / Kubernetes / Helm 部署：本项目是 Agent 宿主进程内的扩展， 不是独立网络服务。它的「部署拓扑」就是 DSH 本身的拓扑（单 Host 进程 + 一个 profile）。 容器化的合理形态是把「DeepSeek Harness + profile + 本 bundle」整体放进容器，而不是单独容器化本 bundle； 本仓库不发布 Docker 镜像，也不宣称支持 K8s——这是设计边界，不是待办事项。

10.2 生产部署建议（单机研究工作站）

┌─────────────── Workstation ───────────────┐
│ DeepSeek Harness Desktop (single process) │
│  ├─ profile: desktop                      │
│  ├─ dsh-armorbreak bundle (source-linked) │
│  ├─ workspace: D:\research\case-001       │
│  │    └─ .armorbreak/{tasks,audit.jsonl}  │
│  ├─ isolation: Docker (optional, L1)      │
│  └─ reports: per-task reports/ (MD/HTML/…)│
│                                            │
│ external tools: optional, PATH-detected    │
└────────────────────────────────────────────┘

• 数据目录：任务/证据属于用户资产，随工作区管理；不要把 .armorbreak/ 提交到仓库。
• 权限：L1/L2 依赖平台审批策略；桌面默认权限预设可能为 danger-full-access，但 ArmorBreak 的 L0–L3 闸门独立生效（不继承宽松策略）。
• 容量规划：每任务证据/报告通常为 KB–MB 级；批量分析需定期清理旧任务（见 known issues）。
• 灾备：备份工作区即可；证据哈希链可独立校验（armorbreak_evidence action=chain）。

10.3 配置全解

10.4 升级与回滚

1. 升级：remove_bundle → install_bundle（或替换源码后重启）；新版本会保留既有工作区数据。
2. 回滚：重新安装旧 tag 源码；任务/证据格式向后兼容（JSON），报告可重新生成。
3. 兼容性：docs/compatibility-matrix.md 记录已验证的 DSH/Cordis/Node 版本；低版本 DSH 缺少 dsh-agent-preset 时 preset 行无法加载（明确失败，不静默降级）。

十一、使用指南 Usage

11.1 9 个模型工具（API 摘要）

11.2 工作流清单

扫描降噪（v1.0.3+）：sast.scan / sast.secrets / sast.deps / sast.sbom 支持可选 excludePaths（按路径子串、大小写不敏感），用于排除规则文件、测试夹具、文档示例等已知噪声，例如：

{ "capability": "sast.scan", "target": "D:\\repo", "workspace": "D:\\work",
  "options": { "excludePaths": ["tests/", "lib/analyzers/sast/rules.js", "docs/known-issues.md"] } }

排除只影响文件枚举，不改变规则、不降低其他文件的覆盖；被排除数量可在结果 data.excludedCount 核对。

11.3 典型场景

1) armorbreak_workflow action=start workflow=BinaryStaticAnalysis target="D:\samples\x.exe" workspace="D:\cases\001"
2) armorbreak_workflow action=run taskId=<id>
3) armorbreak_report taskId=<id> format=markdown

armorbreak_workflow action=start workflow=WebCodeSecurityReview target="D:\repo" workspace="D:\cases\repo-audit"
armorbreak_workflow action=run taskId=<id> maxSteps=4
armorbreak_report taskId=<id> format=sarif

armorbreak_scope action=request purpose="authorized lab validation" operator="alice" \
  networkTargets=["10.20.0.0/16"] riskCeiling=L2
# 平台向用户确认并返回 allowed-once 后：
armorbreak_scope action=activate requestId=<authreq_id>
armorbreak_analyze capability=live.http_probe taskId=<id> options={"url":"http://10.20.0.5/health"}

11.4 报告格式

11.5 错误码体系（策略与执行）

十二、治理与社区 Governance

• 贡献流程：阅读 CONTRIBUTING.md → fork → 分支 → node --test 全绿 → PR； PR 必须包含问题、根因、修复、验证命令与真实结果、剩余限制。
• 提交规范：Conventional Commits（feat(domain): / fix(core): / docs: / test:）。
• 贡献者阶梯：Contributor（被合并 PR）→ Reviewer（持续高质量评审）→ Maintainer（发布与安全响应）； 安全修复遵循 SECURITY.md 私有渠道。
• 行为准则：CODE_OF_CONDUCT.md（Contributor Covenant 2.1）。
• 交流渠道：GitHub Issues（缺陷/功能）、Discussions（问答/设计讨论）、安全公告（私密）。
• 响应期望：issue 首次响应 ≤ 3 个工作日；安全报告按 SECURITY.md 时效。
• 版本策略：SemVer；PATCH=修复，MINOR=新能力，MAJOR=破坏性契约变更；每个 release 附验证结果。

十三、路线图 Roadmap

13.1 已完成

13.2 当前规划（v1.1）

• 模型驱动 E2E：headless + 本地 LLM mock（OpenAI-compatible SSE）验证「模式选择 → 工具调用 → 证据/报告」全链路。
• 外部工具适配器 v1：Ghidra/JADX/Semgrep/TShark/Trivy/Syft 的 argv 数组调用 + JSON 输出解析 + 版本依赖检查。
• UI 工作台：任务/工具/证据中心页面（基于现有 Slot 体系），报告预览。
• 批量分析：一个任务多目标，减少 per-sample 任务持久化开销（当前 36 ms/次）。
• 报告 i18n：英文报告模板。

13.3 中长期

• 隔离提供者抽象（Docker/Podman/WSL2/VM），容器网络 egress 白名单；
• L2 主动测试能力扩展（模板化 HTTP 探测、速率/并发策略、Nmap/Nuclei 适配）；
• 可选的离线漏洞库接入（OSV/NVD），在此之前永不输出「已确认 CVE」；
• 跨平台真机验证（macOS/Linux）、Windows junction/reparse point 完整语义；
• 证据包导出（可独立验证的审计包）与团队审批记录。

13.4 待探索

• 与 DSH 上游的 dsh-plugin-market 索引标准化；插件签名/来源校验；
• 模型侧上下文预算自适应（按任务复杂度选择能力描述粒度）；
• 结构化「假设 → 验证」记录（把 hypothesis 的复核过程也纳入证据链）。

十四、架构决策记录 ADR

ADR-001：零依赖纯 ESM JavaScript，而不是 TypeScript + 构建

• 背景：DSH profile 安装会执行 pnpm；插件在被加载前需要可预测的模块形态。
• 备选：TypeScript + 打包（类型安全）；纯 JS + JSDoc（零构建）。
• 决策：纯 ESM + JSDoc + node --test。
• 影响：安装/升级/审计路径最短、无供应链面；代价是类型检查弱于 tsc（以契约测试补偿）。

ADR-002：Host 服务 + preset 子插件分层，而不是单插件

• 背景：工具必须只对「破甲模式」可见；运行时状态需要进程级共享。
• 备选：全部放 preset（每会话重复实例化）；全部放 Host（污染标准模式工具目录）。
• 决策：Host 行提供运行时/状态路由；preset 子插件注册模式专属工具/技能。
• 影响：标准模式零污染；代价是跨作用域解析需遵循 Cordis 服务规则（已验证）。

ADR-003：代码级策略引擎，而不是提示词约定

• 背景：安全研究的核心风险是越权；提示词可被注入/漂移绕过。
• 决策：ScopePolicy + ExecutionRunner 作为唯一执行咽喉；L3 无代码路径。
• 影响：模型无法通过换工具/换参数绕过；代价是策略变更需要发版（而非改提示词）。

ADR-004：工作区 JSONL + 哈希链，而不是数据库

• 背景：需要可审计、可携带、零依赖的持久化。
• 备选：SQLite（事务/查询）vs JSONL（可读/可校验）。
• 决策：原子写 JSON/JSONL + 哈希链 + 进程内互斥。
• 影响：证据可直接审计/迁移；代价是复杂查询需工具层聚合、跨进程并发不支持。

ADR-005：目录型能力显式 targetKind + 规划期校验

• 背景：v1.0.0 因隐式默认 file 导致目录工作流 4/4 步失败（真实会话复现）。
• 决策：能力必须声明 targetKind；规划阶段校验任务与步骤的兼容性，TARGET_KIND_MISMATCH fail-fast。
• 影响：缺陷在规划期暴露而非运行期；代价是新能力必须正确声明类型。

十五、故障排查与 FAQ

15.1 日志与数据定位

15.2 常见问题

15.3 性能排查

• 解析慢：先用 benchmarks/bench.mjs 定位是 parser 还是持久化；
• runner 调用慢（≈36 ms）：属设计内持久化成本，批量场景复用任务；
• 大文件：检查 truncated 标记与 limits.maxInputBytes（默认 32 MiB）；
• 目录扫描慢：调整 maxFiles/maxBytes，排除 node_modules/.git/dist（默认已排除）。

十六、生态与集成 Ecosystem & Integrations

16.1 DeepSeek Harness 生态

ArmorBreak 是 DSH 的 原生扩展：Cordis Bundle（dsh.bundle.patch）+ Agent preset （@deepseek-ai/dsh-agent-preset）+ 可选 Web 面板（dsh.client）。安装、市场指引与上游链接见 docs/marketplace.md，包括：

• 官方发布指南：https://deepseek-harness.github.io/deepseek-harness/en/develop/basic/publish
• 官方源码：https://github.com/deepseek-ai/deepseek-harness
• 社区市场/精选列表（第三方）：awesome-deepseek-harness-plugins、awesome-dsh-plugin、 dsh-plugin-market、dshbase/dshplugin.store

16.2 外部工具矩阵（可选增强）

16.3 扩展点

新增能力 = 新增 lib/analyzers/<domain>/manifest.js + 测试；核心通过契约自动发现。 详见 docs/CONTRACT.md。

十七、案例研究 Case Studies

以下为真实会话/路由执行记录（参考主机，非企业生产环境）；数据来自任务证据与报告， 不做匿名化之外的夸张修饰。

案例 1：真实 PE 样本的 7 步静态分析

• 目标：notepad.exe（360,448 B，SHA-256 468ffe12…4577e）
• 路径：armorbreak_workflow BinaryStaticAnalysis
• 结果：7/7 步 DONE，证据 21 条，发现 6 条（全部 hypothesis 或 info），报告生成； 上下文补证（Authenticode 有效、Microsoft 签名）用于降低误报而非制造结论。
• 经验：证据链 + 验证等级让「合法系统组件」与「可疑行为组合」的区分可复核。

案例 2：目录型工作流缺陷的发现与修复

• 现场：对源码目录执行 WebCodeSecurityReview，4 步全部 TARGET_NOT_FILE。
• 根因：sast 能力未声明 targetKind；规划器默认 file；错误提示自相矛盾。
• 修复：目录声明 + 规划期 TARGET_KIND_MISMATCH + env.readFile Buffer 契约 + 集成测试。
• 经验：隐式默认值在安全工具中是缺陷源；契约显式化 + 规划期 fail-fast 比运行期试错更可靠。

案例 3：工具输出无损 JSON 故障

• 现场：armorbreak_health 连续 3 次失败，value is not lossless JSON。
• 根因：状态快照携带 capability 函数字段，Harness 审计通道拒绝非 JSON 值。
• 修复：移除冗余字段 + 工具出口深度净化 + 4 个回归测试。
• 经验：工具输出是安全边界的一部分；无损 JSON/循环引用/undefined 必须在出口统一治理。

十八、许可证 License

• MIT License — 见 LICENSE。Copyright (c) 2026 LYL-Z。
• 第三方组件：本项目零运行时依赖，不打包第三方库；外部工具（Ghidra/JADX/…）由用户自行安装， 各自遵循其许可证，本项目不重新分发。
• 文档截图：docs/media/ 中的截图由项目作者/测试环境提供，随 MIT 文档许可使用。
• 徽章服务（shields.io）与 GitHub Actions 为外部服务，不在本仓库许可范围内。

十九、致谢 Acknowledgments

• DeepSeek Harness / Cordis 团队：提供了可扩展的 Host、Agent preset、工具/技能/审批、Web 插件体系； 本项目的全部集成点均来自其公开源码与文档。
• 真实会话测试者 LYL-Z：在安装后的真实会话中报告了目录型工作流、并发哈希链、UTF-8、realpath、 端口匹配、YAML 原型污染等缺陷；这些反馈直接塑造了 v1.0.2。
• 并行分析能力实现小组：binary/forensics、android/network、web/sast/ctf 三个域的实现与测试由 子代理协作完成（按 Lead 契约集成与复核）。
• 社区生态：awesome-deepseek-harness-plugins、awesome-dsh-plugin、dsh-plugin-market 等 社区索引与市场为本项目的分发路径提供参考。
• 灵感来源：Cordis 组合模型、OWASP ASVS/CWE/CVSS/SARIF 标准、DFIR 工具链的「证据优先」实践。

附录：文件结构与文档索引

dsh-armorbreak/
├── package.json              # Bundle 清单 + dsh.bundle/topic metadata
├── cordis.patch.yml          # Host 行 + preset-armorbreak 声明
├── index.js                  # Host：/armorbreak/state 只读路由
├── client.js                 # 浏览器：composer dock 状态卡
├── tools.js                  # 9 个模型工具 + 审批桥 + 无损 JSON 出口
├── skills.js                 # 7 个内置技能注册
├── lib/core/                 # 运行时（策略/任务/证据/审计/执行/报告/健康）
├── lib/analyzers/            # 8 个域、39 个能力（各自 manifest.js）
├── skills/*.md               # 技能正文
├── locale/{en,zh}.json       # 插件显示元数据
├── icon.svg
├── docs/                     # 审计/架构/安全模型/验收/兼容性/已知问题/路线图/市场/基准
├── benchmarks/               # 可复现基准脚本与结果
├── scripts/                  # 文件清单生成、测试临时目录清理
├── tests/                    # 178 个 node:test 用例
└── .github/workflows/ci.yml  # 双平台 CI

ArmorBreak · 破甲模式
Authorized reverse engineering & security research, native to DeepSeek Harness.
Evidence or it didn't happen.

MIT © 2026 LYL-Z