siq-agent-security 仓库指南

本仓库是 SIQ Agent Security 产品的独立代码仓（受 /home/maoyd/siq/AGENTS.md 工作区指南约束，本文件在其之上细化）。

边界

• 不 import 兄弟仓库内部代码、不查询兄弟仓库数据库；
• SIQ 专属能力只在 connectors/siq（当前未实现），经版本化 API/事件接入；
• 合同变更先改 packages/contracts/（升版本），再同步实现方与测试。

事实源顺序

1. packages/contracts/*.schema.json + connector-protocol.v1.md（合同事实源）；
2. 设计文档 v0.2 与 ADR（docs/adr/）；
3. 实现与测试。

siq-agent-security（本地 Agent 形态，ADR-011）在此之上再加一层：ADR-011 → docs/agentshield-design-v1.md（方案）→ docs/agentshield-dev-spec-v1.md（规格，实现以此为准）→ 合同。W7 本地台账增量见 docs/agentshield-local-ledger-dev-plan-v1.md（先回写规格再实现）。规格与实现不一致时先改规格再改代码；就近约定见 apps/agentshield/AGENTS.md。

安全不变量（任何改动不得破坏）

1. tenant_id 只从验证身份派生；对象级端点先定位（404）后权限（403）；
2. Secret 明文不落库、不进日志/审计/outbox（只存哈希或引用）；
3. 审计与状态变化同事务；高风险写操作审计缺失即失败关闭；
4. Edge 凭据只存哈希，吊销即时生效（每次请求在线校验）；
5. 模型输出不能直接创建 effective 权限或通过审批；
6. 每批 evidence 必须被本批 candidate 引用；
7. 生产模式（非 SIQ_AS_DEV）禁止 SQLite、自动建表、X-Dev-* 身份头。

siq-agent-security 本地模式（apps/agentshield/）额外遵守：

8. effective 只能来自后端读回；admission 只产 declared，grant 只产 declared/inferred，receipt 只产 observed；
9. 签名私钥只存状态目录，适配器、UI、SKILL.md 脚本永不持有；准入/签发/回执文件只追加或新建，不改写；
10. 被扫描的 Skill 内容与钩子参数永不执行、导入或 eval；持久化只存 sha256 与脱敏、限长的 excerpt；
11. enforcement_mode=block 下决策服务不可达即拒绝（fail-closed）；普通 policy 的 audit_only/warn 保留 allow + advisory_action。按用户当前 Provenance-Bound Effect V1 模板，无效必需 Authority 为独立 hard deny，任何模式不得放宽；
12. 「有威胁模式」≠「隔离」：能力需求（sudo、出网、写路径、allowed-tools）升级为 declared 事实交 grant；只有欺骗用户、隐藏指令、提示注入、凭据外传、完整性失败才 quarantine。

开发约定

• Python ≥3.12：uv sync --dev、uv run ruff check app、uv run pytest；迁移必须 Alembic 且可在干净库回放；
• Go ≥1.22：标准库优先；Connector 只经 edge/agent/protocol 共享包引用合同类型；apps/agentshield 仅 stdlib，第三方依赖需 ADR；
• 规则包 threat_rules.v1.json 是 Python/Go 共享文件（apps/control-api/app/data/ 与 apps/agentshield/internal/rulepack/data/ 两份由测试锁定一致）：模式必须 RE2 兼容且 CPython 语义等价，改动两侧测试都要跑；
• 平台适配器（adapters/runtime/*-agentshield/）只做钩子 ↔ HTTP 映射，不含规则、判定或密钥；改写用户配置（如 WorkBuddy settings.json）必须先备份、可卸载；
• Skill（skills/siq-agent-security/）遵守 agentskills.io 规范：description ≤60 字符一句话句号结尾；正文明确「裁决由二进制产出，模型不判断安全性」；
• Web：npm ci && npm run build；token 永不落 localStorage；
• 提交：<scope>: <简洁主题> 格式（如 contracts:、control-api:、edge:、web:、agentshield:、adapters:、skills:、rulepack:、docs:）；安全修复必须带负向测试证明旧行为被拒绝；
• 推送注意：本机环境变量 GITHUB_TOKEN 已失效，gh/git 推送用 env -u GITHUB_TOKEN gh/git ... 走 keyring 凭据。

测试要求（按变更类型）

当前仓库组织实施（2026-09-19）

用户已要求以仓库架构调整方案为持续目标，允许在本仓库实施导航、索引、路径守卫与发行工具的适用 RA 批次。执行入口为 docs/development/current.md，整理进度为 RA 台账。历史阶段指令按其冻结对象和授权周期适用，不把旧 V5 停止开发句子覆盖本次明确授权；原安全不变量、历史签名与证据保护继续适用。产品功能、平台支持与发行身份不由目录整理自动改变。工作树删除不属于本轮范围。

以下阶段记录只说明当时的范围、授权与冻结对象；当前任务从上方开发导航进入，不把历史“当前目标”或旧分支指令应用到新一轮开发。

历史开发模板（V5 比赛冻结周期）

当前目标为 Final Release & Submission Freeze V5 原文。 从最新 main 创建 codex/hackathon-final-release-v5，仅允许文档、发布工具、证据与治理准备，以及有负向测试证明的真实 P0 修复。 唯一当前状态为 final-submission-state.md。 停止功能开发；不重构 runtime security architecture，不新增 Managed Linux、委派、沙箱、框架或服务。 本轮 submission source 固定为当前 main；V5 分支只承载收口材料和发布工具。 未经明确 publisher / governance authorization 不发布或改仓库设置，准备可审阅材料并记录 external_manual。 历史 V4/V3/V1 需求与证据保留，V5 原文覆盖冲突的分支、状态和提交口径。

历史研究开源授权（2026-09-08）

用户已要求直接实施研究开源，并确认自有代码和原创研究材料属于本人。研究分支 codex/research-open-source-r1 基于 V5 文档提交，执行 docs/open-source-research-plan-20260908.md；实际状态见 docs/research/operations-20260908.md 和任务台账。此授权覆盖许可、社区文件、仓库治理、远端提交和研究复现准备，不重复套用上方 V5 的未授权占位状态。V5 比赛源码、制品、视频与原分母仍冻结，不改 runtime 架构。新制品必须有新身份，不伪造正式签名、DOI、外部复现或论文接受。

历史个人体验与团队管理授权（2026-09-10）

用户已明确要求以 个人体验与局域网团队任务书 为持续目标实施并落盘。此新周期允许在当前项目内增量修改规格、合同、代码、测试和交付工具，不把旧 V5 停止功能开发要求误用于本次已授权工作；原比赛和发布快照仍冻结。任务进度与证据见 开发台账。先个人 UX-000–015，后团队 LAN-001–006；缺少真实 OS/平台证据的项不得记为通过。不得擅自提交、推送、发布或修改远端治理设置。常规实现选择按已确认范围自主推进。