TP-Spec-Coding Runtime · Contract v5.3.8

Spec-Driven Engineering
for Autonomous Coding Agents

TP-Spec-Coding 是面向复杂软件工程的多角色契约驱动运行时(Spec-Driven Runtime)。通过确定性 Resolver、SQLite 事件溯源账本、L0–L3 风险分级门禁与三层知识记忆体系,彻底终结 AI 协作研发中的需求幻觉、静默越权与状态漂移。

v5.3.8
Base Contract
4 Domains
Zero-Scan Dispatch
L0 – L3
Adaptive Risk Gate
SHA-256
Fenced Event Ledger

低上下文路由与确定性状态机

将“产品入口路由”、“领域生命周期编排”与“持久化项目状态面”严格解耦,杜绝把入口壳变成臃肿的第二套编排器。

Control Role · tp-spec-coding

四域低开销分发协议(Zero-Scan Domain Dispatch)

默认唯一入口仅消费当前用户输入、显式指令、project-binding.yaml 身份与活动任务紧凑摘要;不预扫描业务仓库、不预载全量角色正文,直接按领域移交专业生命周期:

tp-spec-coding Low-Context Entry Domain Lifecycle role-catalog.yaml SQLite + JSONL Fenced Transactions continuation SHA-256 View
01 / software
tp-software-lifecycle
需求澄清、架构设计、代码实现、对抗式审查、测试验证与精确交付闭环。
02 / wiki
tp-wiki
代码结构索引与模块级导航维护,遵循 content-systems 覆盖契约。
03 / knowledge
tp-knowledge
跨任务长期特性契约(FEAT)沉淀,默认隔离检索 current project + shared。
04 / base
tp-base-maintenance
Base 契约升级、Runtime Rebind、托管区同步与用户级外部 Skill 治理。
Event-Sourced Ledger

防伪造双层账本(SQLite Runtime + JSONL Projection)

所有任务状态流转、安全取证(SECURITY_EVIDENCE_RECORDED)与质量门禁均经由正式 CLI 事务写入 .tp-spec/db/<project>.db,并自动生成带有 source_digest 与 flush_id 校验指纹的派生视图。

{
  "view_schema": "tp-spec.task-view/v1",
  "generator_version": "5.3.8",
  "workflow_mode": "standard",
  "applicable_obligations": {
    "development": true, "verification": true, "review": true,
    "delivery": true, "acceptance": "required", "knowledge": true
  },
  "flush_id": "CHECKPOINT-17013877d2e543fa98eec5d62e933850"
}
Portable Binding

去 Junction 化与跨机可携带绑定

彻底废弃易损坏的旧式目录软链(.tp-spec/agents、wiki、scripts)。项目仅保留纯净身份声明,机器级路径由 tp-spec base resolve 动态解析。

# .tp-spec/config/project-binding.yaml
schema: tp-spec.project-binding/v1
project:
  id: idc
  wiki_id: idcproject
  knowledge_id: idc
base_version: 5.3.8

三层事实源与按需热记忆架构

严格区分技术事实、导航、长期契约与热记忆边界,防止大模型将历史临时授权或过期草稿推导为当前执行权限。

层级 (Tier) 载体位置 (Artifact Location) 权威语义与读写边界 (Authority & Boundary)
Source Code Workspace Repositories 唯一当前技术实现事实源(Single Source of Technical Truth)。任何文档、原型或历史记录不得推翻已核实的源码与库表结构。
Root Entry AGENTS.md 分为 tp-spec-base:managed 托管区与项目自有薄入口。自有区仅保留硬约束与问题现象指针,同步 Base 时绝不覆盖项目自有规则。
Hot Memory .tp-spec/memory/PROJECT.md
.tp-spec/memory/INDEX.md
Git 可携带的稳定规则(Constraints / Verification / Diagnostics / Rules)与高复用项目级 Skill。经由 tp-memory-capture 门禁写入,不存机器秘密。
Task Ledger .tp-spec/tasks/TASK-* 区分 standard 与 quick 模式。维护唯一有效需求区(requirement.md)、去重澄清矩阵与不可篡改的 events.jsonl 审计轨迹。
Knowledge & Wiki tp-spec knowledge search 沉淀跨任务长期有效的特性契约(如 IDC-FEAT-*)。默认限制在 current project + shared 作用域,禁止未经授权的全局漫游扫描。

核心运行时指令集

通过统一的 tp-spec 命令行驱动契约解析、状态流转、技能按需读取与遥测记录。

Resolution & Skills

基础解析与按需读取

# 解析当前工作区绑定的 Base / Wiki / Knowledge 根路径
tp-spec base resolve --workspace-root .

# 按精确 ID 读取内置领域或专业角色规范
tp-spec skill read --id tp-software-lifecycle --json

# 发现用户级外部扩展技能摘要
tp-spec skill list --query external:local: --json
Workflow & Knowledge

任务编排与知识检索

# 查询活动任务的下一步责任角色与门禁要求
tp-spec workflow next --task TASK-22644 --db .tp-spec/db/idc.db --json

# 在当前项目与共享域检索长期 Feature 契约
tp-spec knowledge search --query "IDC-FEAT-095" --json

# 在 TP-Spec-Coding 源码根启动本地只读可视化工作台
npm run dev

版本演进与架构变更记录 (#changes)

追踪 908794920/TP-Spec-Coding 从早期规约脚本到 v5.3.8 契约驱动运行时的关键技术迭代与 Schema 契约演进。

Latest Contract: tp-spec.artifact-contract/v5.3.8
v5.3.8 Latest Stable Runtime & Modes
git: 059fb08 14 files +428 -112 2026-10
  • 任务模式精细化分流(Task Necessity & Mode Gate):明确普通局部修改直接使用对应能力闭环,不因接入 TP-Spec、调用 Skill 或运行测试自动创建正式 Task;正式任务严格区分 standard(全义务矩阵校验)与用户显式授权的 quick 模式。
  • 外部能力发现与领域转交(External Skill Discovery):新增 tp-spec skill list --query external:local: --json 低成本摘要协议,显式区分“管理外部 Skill(tp-external-skill-management)”与“调用外部方法执行业务研发”的授权边界。
  • 只读安全取证契约(Security Authority v1):在 events.jsonl 中引入 SECURITY_EVIDENCE_RECORDED 事件与 SHA-256 证据链哈希,确保现网只读排查(effect_scope: read_only)与业务写入严格隔离,不将取证推导为发布或验收 PASS。
  • 按需热记忆沉淀(tp-memory-capture):规范根 AGENTS.md 薄入口与 .tp-spec/memory/PROJECT.md 分节同步机制,写入后强制读回校验可发现性。
Inspect Contract Diff · tp-spec.security-authority/v1 & mode_source ▼
{
  "event_type": "SECURITY_EVIDENCE_RECORDED",
  "detail": {
    "security_schema": "tp-spec.security-authority/v1",
    "security_payload": {
      "context": { "effect_scope": "read_only", "security_changes": [] },
      "purpose": "investigation_only"
    },
    "schema_version": "5.3.8",
    "result_status": "RECORDED"
  }
}
v5.3.0 Deterministic View
git: 64bcb27 19 files +612 -184 2026-09
  • 派生接续视图(generated/continuation.md):由 Runtime 根据 status.yaml、events.jsonl、requirement.md 与 acceptance.md 自动计算生成,附带 source_digest 与 content_digest,禁止人工手写当前角色或伪造进度。
  • 本地可视化工作台(Workbench Isolation):支持在 TP-Spec-Coding 源码根通过 npm run dev 按需启动只读工作台,零后台轮询、零业务仓库前端复制污染。
  • 上下文遥测(Context Telemetry):在 checkpoint / review / verify / delivery 阶段支持挂载 --context-usage-json,以真实工具调用证据记录 source_followup(none | targeted | broad)。
Inspect Contract Diff · tp-spec.task-view/v1 Projection Header ▼
generated_view: true
view_schema: "tp-spec.task-view/v1"
generator_version: "5.3.8"
source_digest: "sha256:22034f0053d88b4f90f3380285844b022f7544df262f7a339cb8f222c8090aa6"
flush_id: "CHECKPOINT-17013877d2e543fa98eec5d62e933850"
v5.2.0 Portable Binding
git: b1c2f08 23 files +790 -340 2026-08
  • 去 Junction 化与跨机器可携带绑定:引入 .tp-spec/config/project-binding.yaml 与 ~/.tp-spec/installation.yaml,通过 tp-spec base resolve 动态定位 Base、Wiki 与 Knowledge,彻底移除对机器绝对路径和旧目录软链的依赖。
  • SQLite Runtime Rebind:将 project.root_path 定义为当前机器可安全重绑定的本地定位缓存(Locator Cache),不再作为跨机身份标识。
  • 托管区安全同步(Managed Block Sync):通过 <!-- tp-spec-base:managed:start/end --> 边界标记实现底座规则无损升级,100% 保护项目自有约束不被覆盖。
v5.0.0 V5 Foundation
git: 675bb3f 41 files +1,840 -620 2026-07
  • 确立唯一默认入口 tp-spec-coding:重构 governance/role-catalog.yaml 与 workflow.yaml,将需求管理(tp-requirements-manager)、项目管理(tp-project-manager)、架构、开发、测试与评审纳入统一契约编排。
  • 单一有效需求区契约:强制在 requirement.md 的 tp-spec:current 区块维护唯一有效业务语义,历史被替代决策标记 SUPERSEDED 并保留追溯链。