Factory.ai Droids：无公开源码、但文档披露到函数名级的企业级 agent harness

Factory.ai (Droids)

一句话定位

Factory.ai 的 Droid CLI 是一个闭源的企业级 coding agent harness（对标 Claude Code / Cursor CLI），其 CLI 二进制/npm 包本身不开源，但官方文档（docs.factory.ai）与工程博客（factory.ai/news）的披露深度异常高——内部函数名（checkFileAccess()、checkNetworkAccess()）、JSON hook schema、settings 合并语义、甚至一条完整的 LoRA 微调流水线（Droid Shield 2.0）都被公开写清楚，使其成为”无源码但可做源码级调研”的少数样本之一。

核心架构总览（目录结构关键路径 + 引用的 commit）

• 无应用源码可读：github.com/Factory-AI/factory 仓库在 commit fdf8712a06b566cbcbd3920ae01e52be3f462ab9（“docs: add CLI changelog entry for v0.162.0 (#1268)“，2026-07-01，540 commits，41 分支，主要提交者为 factory-droid[bot] 自举）时，根目录只有 .github/、docs/、README.md、.gitignore——即该仓库是 docs.factory.ai（Mintlify 站点）的内容源，不含任何应用逻辑代码。
• 分发方式：curl -fsSL https://app.factory.ai/cli | sh（macOS/Linux）、irm https://app.factory.ai/cli/windows | iex（Windows）、或 npm -g install droid。CLI 版本号约 v0.162.0（据 changelog 推断，截至 2026-07-01）。
• 关联但独立的公开仓库（仅确认存在，未克隆细读）：Factory-AI/droid-sdk-typescript、Factory-AI/droid-sdk-python、Factory-AI/droid-action（GitHub Action）、Factory-AI/factory-plugins（插件市场）、Factory-AI/eslint-plugin。
• 两个真实开源 ML 产物（非 harness 代码，但是可验证的模型权重）：huggingface.co/factoryai/shield-risk-r16-c15、huggingface.co/factoryai/shield-dg-r64-c15——均为 Qwen 3.6 35B A3B 之上的 PEFT LoRA adapter，属于 Droid Shield 2.0 秘钥检测流水线的产出（详见”自进化能力”节）。
• 本地配置/会话路径（从 hook payload 中反复出现的字段还原）：项目级配置 .factory/droids/（Custom Droids）、.factory/skills/（Skills）、.factory/AGENTS.md；用户级 ~/.factory/droids/、~/.factory/skills/、~/.factory/AGENTS.md、~/.factory/.ssh/（Droid Computers 专用 SSH 密钥）；会话持久化 ~/.factory/projects/<project-hash>/<session-id>.jsonl。

以下各维度论断均标注来源文件（保存于 /Users/zhao/projects/self-wiki/ai-research/sources/harness/factory-ai/）与对应章节标题，全部来自 docs.factory.ai / factory.ai/news 官方一手材料，非源码。

Agent Loop（主循环 / 何时继续何时停）

• 交互式 CLI（droid）：有状态 REPL，两种交互模式——Auto（直接执行）vs Spec Mode（只读规划，需显式批准才能进入实施），Shift+Tab 切换。（auto-run.md “How approvals work”）
• 无头模式（droid exec）：一次性任务执行器，默认 spec-mode/只读；--auto {low,medium,high} 解锁不同级别的写操作；--skip-permissions-unsafe 绕过全部检查（文档明确标注”unsafe”，“use only in isolated sandboxes”）。（droid-exec.md “Execution model”, “Autonomy Levels”）
• 循环终止由 Stop / SubagentStop hook 事件控制：官方原文”Runs when Droid has finished responding. Does not run if the stoppage occurred due to a user interrupt.”；hook 可返回 "decision": "block" + reason 强制 Droid 继续而非停止——这是暴露给用户/开发者的字面意义上的”continue/stop”控制点；stop_hook_active 字段防止 Stop-hook 无限循环。（hooks-reference.md “Stop”, “Stop and SubagentStop Input”, “Stop/SubagentStop Decision Control”）
• 工具调用的 turn 边界是 PreToolUse → 工具执行 → PostToolUse；PreToolUse hook 可 allow/deny/ask，甚至通过 updatedInput 在工具执行前改写其输入——即循环拥有逐工具调用级别的可编程拦截点，不只是逐 turn 级。（hooks-reference.md “PreToolUse Decision Control”）
• 会话续接/分叉是显式 CLI 状态：--session-id <id>（续接）、--fork <id>（从已有会话分叉并继续）。（droid-exec.md CLI flags）
• Mission 模式是独立的循环形态：--mission 启动多 agent 编排，--worker-model / --validator-model 角色分离——即 Mission 的”循环”是 worker 产出/validator 校验，而非扁平的单 agent ReAct 循环。（droid-exec.md “Mission mode flags”; missions.md “How it works”）

记忆与上下文管理（压缩、长期记忆、会话持久化）

• 压缩触发点：PreCompact hook，在 Droid 即将执行 compact 操作前触发，matcher 区分 manual（用户手动 /compact，携带 custom_instructions）与 auto（上下文窗口满触发）。（hooks-reference.md “PreCompact”）
• 会话持久化：每个会话的完整 transcript 存为 .jsonl 文件，路径 ~/.factory/projects/<project-hash>/<session-id>.jsonl（transcript_path 字段出现在每个 hook 的输入 payload 中，示例：/Users/.../.factory/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl）。（hooks-reference.md “PreToolUse Input” 示例及全文反复出现）
• SessionStart hook 在 startup、resume（来自 --resume/--continue//resume）、clear（来自 /clear）、compact 时触发；文档特别指出”resume…currently does start a new session under the hood”——即 resume 实现为”回放进新会话”而非真正的进程级恢复。SessionStart 可注入 additionalContext（多个 hook 的输出会被拼接）——这是会话启动时加载外部上下文（issue、近期 diff 等）的机制。（hooks-reference.md “SessionStart”, “SessionStart Decision Control”）
• SessionEnd 在 reason ∈ {clear, logout, prompt_input_exit, other} 时触发，仅用于清理/统计记录，不能阻止会话终止。（hooks-reference.md “SessionEnd”）
• 跨会话/长期/组织级记忆 = AutoWiki，这是本维度最值得记录的发现：
  • 多阶段、多 agent 生成流水线：Survey（两遍扫描：先结构性扫 README/manifest/CI，再语义性深扫路由/API/服务类/DB schema/feature flag）→ Plan → Generate（按依赖顺序逐页生成）→ Visual capture → Video rendering → Upload。（wiki.md “How it works”）
  • 增量再生成：首次运行分析全代码库；后续运行对比存储在上一版 wiki 元数据里的 commit hash 做 diff，只重新生成受影响页面，未变化页面原样带过。（wiki.md “Always current”）
  • 同时持久化到 4 个 surface：Factory 云端 web viewer（按 commit/branch/timestamp 版本化）、GitHub 原生 wiki tab（自动同步）、会话内通过 read_wiki 工具调用（示例：read_wiki tiangolo/fastapi -> 42 pages）、以及提交进代码仓库本身的 droid-wiki/ 目录（随 fork/clone 一起传播，可被 diff/blame）。（wiki.md “Where the wiki lives”）
  • 本质上，Factory 对”长期记忆”的回答不是向量数据库/RAG 记忆层，而是一份会再生成、版本化、提交进代码库的文档产物，人类和 Droid 会话都查询它。
  • AGENTS.md 更像是静态/注入式上下文而非动态记忆：发现顺序为 CWD → 向上找最近的父级直到仓库根 → 子文件夹 AGENTS.md → 个人覆盖 ~/.factory/AGENTS.md，就近文件优先。（agents-md.md “File locations & discovery hierarchy”）
  • 未发现基于向量嵌入的长期记忆存储、用户偏好记忆，或独立于 AutoWiki + transcript 文件之外的”对历史会话做 RAG”功能。（未发现不等于确证不存在，仅为披露范围内的结论）

工具体系（定义/调用协议/注册/权限）

• 内置工具注册表（在 hooks-reference.md 与 sandbox.md 中被反复明确点名）：Read、LS、Grep、Glob、Edit、Create、ApplyPatch、Execute、FetchUrl、WebSearch、Task（subagent 派发）、TodoWrite（每个 custom droid 自动携带）、GenerateDroid（元工具，从文本描述脚手架生成新 custom droid）。
• 工具类别 → 具体工具 ID 映射（用于 custom droid 的工具范围限定）：
  • read-only = Read, LS, Grep, Glob
  • edit = Create, Edit, ApplyPatch
  • execute = Execute
  • web = WebSearch, FetchUrl
  • mcp = 由已配置的 MCP servers 动态填充 （custom-droids.md “Tool categories → concrete tools”）
• 逐工具的权限校验发生在工具实现内部，而非仅在上层策略层：官方原文披露了具体内部函数名——“File tools (Read, Edit, Create, LS, Grep, Glob, ApplyPatch) — checkFileAccess() before every operation”，“Execute tool — shell commands wrapped in OS sandbox”，“FetchUrl — checkNetworkAccess() against allowedDomains”。（sandbox.md “What’s included”）
• 风险分级的 autonomy 门控：每个 Execute 命令/MCP 工具调用携带风险标签（low|medium|high）；Autonomy Level（Off|Low|Medium|High）决定其自动执行或提示确认。额外的 commandAllowlist/commandDenylist/commandBlocklist 设置叠加其上——blocklist “can never run…holds even under full autonomy, auto-run, or --skip-permissions-unsafe”，命令解析逻辑会破解 wrapper-shell/绝对路径/引号绕过等 trick。（auto-run.md “Choose a level”, “Command allowlists, denylists, and blocklists”）
• MCP 作为工具注册协议：droid mcp add <name> <url> --type {http|sse|stdio}；支持 40+ 注册表 server（Sentry、Linear、Figma、Stripe、Notion、Vercel 等）；HTTP server 支持 OAuth；/mcp 交互式管理器可按 server 启用/禁用/查看工具；企业级 MCP 策略可在组织级允许/禁止特定 server。（mcp.md）
• Skill 系统也是动态工具/工作流注册的一种形式：SKILL.md 定义的技能被合并进 / 命令命名空间以及 Droid 可自主调用的范围。（skills.md）
• MCP 工具在 hooks 中的命名约定：hooks-reference.md 存在专门的 “Working with MCP Tools” 一节确认了此机制存在，但本轮未读取全部细节（遗留缺口，见文末”开放问题”）。

Prompt 设计（系统提示结构、动态组装）

• AGENTS.md 是主要的声明式 prompt 注入面：纯 Markdown，标题作为 Droid 识别的语义提示（# Build & Test、# Architecture Overview、# Security、# Git Workflows、# Conventions & Patterns）；被显式定位为跨工具通用约定，Cursor、Aider、Gemini CLI、Jules、Codex、Zed 均可读取同一文件。（agents-md.md “1. What is AGENTS.md?”, “6. Templates & examples”）
• Subagent 的自定义系统提示：每个 Custom Droid 的 .md 文件有 YAML frontmatter（name、description、model、reasoningEffort、tools、mcpServers）+ 一段 Markdown 正文，正文本身即该 subagent 的系统提示。（custom-droids.md “4. Configuration”）
• 通过 hooks 做运行时提示增强：UserPromptSubmit hook 可在 Droid 处理用户输入前注入 hookSpecificOutput.additionalContext，或以面向用户（非面向模型）的 reason 直接拦截该次输入；SessionStart hook 同样在启动时注入 additionalContext，多个 hook 的输出会被拼接。即：prompt = 静态 AGENTS.md/subagent 系统提示正文 + 按事件分层的 hook 注入上下文。（hooks-reference.md “UserPromptSubmit Decision Control”, “SessionStart Decision Control”）
• CLI 级系统提示覆盖：droid exec --append-system-prompt <text> / --append-system-prompt-file <path>——为无头运行在系统提示末尾追加任意文本。（droid-exec.md CLI options table）
• Droid Shield 2.0 训练使用了明确披露的固定系统提示（随开源权重一起发布于 Hugging Face，官方称”the exact system prompt used for training”），但提示文本本身未在博客正文复现，仅作为附带产物被引用。（droid-shield-2.0-blog.md “Open weights”）
• 训练期 judge prompt 的结构（间接揭示了一个数据标注提示模板）：每条训练样本为 {input: {extension, lines, focus_line}, label: {verdict: S|B, reason}}——这是被提示去填写此 schema 的 LLM judge（GPT-5.5 主评委，Opus 4.8 仲裁）的模板形状。（droid-shield-2.0-blog.md “Data”）

Router / 编排（任务分解、多 agent、子 agent）

• Custom Droids = subagent 原语：通过 Task 工具以 subagent_type 参数派发，解析到 <repo>/.factory/droids/（项目级、共享）或 ~/.factory/droids/（个人级）下的 .md 文件；名称冲突时项目级覆盖个人级。每个 subagent 拥有独立上下文窗口（“Context isolation — each subagent runs with a fresh context window, avoiding prompt bloat”）、自己的 model/tools/MCP-server 白名单。Task 派发的 subagent 在 Auto 模式下强制 --auto high，在 Spec Mode 下无论父级设置如何均为只读。（custom-droids.md “1”, “2”; auto-run.md “Where Autonomy Level applies”）
• Claude Code subagent 导入：Droid 可直接导入 ~/.claude/agents/ 或 <repo>/.claude/agents/ 的定义，将 Claude Code 的工具名/模型族（如 sonnet -> 首个可用的 Sonnet 模型）重映射为 Custom Droid .md 文件，对无法映射的工具给出校验警告。这是一个具体的跨 harness 互操作功能，而非仅停留在概念兼容层面。（custom-droids.md “5.5 Importing Claude Code subagents”）
• Factory Missions = 更高阶的编排器，与临时性的 Task 工具 subagent 派发不同：/missions 启动一段协作式规划对话（非一次性），产出结构化的功能/里程碑计划；批准后控制权交给 “Mission Control”，由其管理跨 agent 的执行并追踪计划进度。Missions 需要 High autonomy 或 --skip-permissions-unsafe，管理员可限制谁能启动 Mission。（missions.md “What Missions do”, “How it works”; auto-run.md “Where Autonomy Level applies”）
• Mission 执行有独立的 worker vs validator 模型角色（droid exec --mission 的 --worker-model、--validator-model 参数），即编排层是生成器/评判器多 agent 模式，而非简单地”派生 N 个相同的 subagent”。（droid-exec.md “Mission mode flags”）
• Factory 明确承认关键架构问题尚未解决/公开表示未证实：官方原文”Is parallelization necessary? Running multiple agents in parallel sounds good in theory, but does it actually produce better results than sequential execution? We are testing this.”——这是罕见的、直接来自厂商的设计不确定性坦诚披露。（missions.md “Open questions”）
• AutoWiki 的生成本身就是多 agent 的：“Large codebases are hard to document well with a single linear pass…AutoWiki splits the work across specialized agents, each scoped to one facet of the repository.”（wiki.md “How it works”）
• 深度安全审计被明确编排为 Mission：/security-review deep audit 在 Mission 内运行——“orchestrated multi-agent missions that scan every source file, cross-reference findings, and validate exploitability before reporting.”（security-review.md “Regular codebase audits on GitHub”）
• Missions 的启用门槛是 Agent Readiness Model 达到 Level 4/”Optimized” 或以上（建议值），因为 Mission 会对目标应用运行自己的 QA 来自我纠错——这把编排能力与仓库自动化成熟度直接绑定。（missions.md “For optimal outcomes”）

Skill / 插件体系

• Skills：目录 .factory/skills/<name>/，内含 SKILL.md（或 skill.mdx）YAML frontmatter（name、description、user-invocable [默认 true]、disable-model-invocation [默认 false]）+ Markdown 指令 + 可选的支持文件（脚本/schema/checklist）。发现路径包括 <repo>/.factory/skills/、~/.factory/skills/（个人级）、<repo>/.agent/skills/（跨工具兼容路径）。（skills.md “What is a skill?”, “Where skills live”, “Frontmatter reference”）
• 旧版自定义 slash command 已被合并进 skill 体系：.factory/commands/review.md 与 .factory/skills/review/SKILL.md 产生完全相同的 /review；旧格式文件仍可直接使用不受影响。（skills.md 引言）
• 调用控制矩阵：默认为用户（/skill-name）和模型均可调用；disable-model-invocation: true = 仅用户可调用（用于有副作用的工作流如 /deploy）；user-invocable: false = 仅模型可调用（背景知识型，非用户有意义的直接操作）。（skills.md “Control who invokes a skill”）
• Plugins 是比 Skills 更宽的独立打包单元——通过 Droid Control 功能文档确认：droid plugin marketplace add https://github.com/Factory-AI/factory-plugins，然后 droid plugin install droid-control@factory-plugins --scope user。插件可携带 hooks（hooks/hooks.json 自动合并，${DROID_PLUGIN_ROOT} 环境变量用于引用插件内文件，来自多个来源的 hook 在同一事件上并行执行）和 slash command（droid-control 插件自带的 /demo、/verify、/qa-test）。（droid-control.md “Get started”, “Commands”; hooks-reference.md “Plugin hooks”）
• 公开插件市场仓库：github.com/Factory-AI/factory-plugins（仅通过 README 链接和 droid-control 安装说明确认存在，本轮未独立克隆细读）。

自进化能力（自我改进 / 学习型记忆 / eval 驱动纠错）

• Agent Readiness Model 是最接近”对环境本身做形式化 eval”的机制：5 个等级（Functional → Documented → Standardized → Optimized → Autonomous），9 个技术支柱（Style & Validation、Build System、Testing、Documentation、Dev Environment、Debugging & Observability、Security、Task Discovery、Product & Experimentation），逐级晋升需在上一级标准上达到 80% 通过率才能解锁下一级，评估同时在仓库级和 per-app 级（monorepo 感知，例如 3/4 apps 通过）进行。（agent-readiness.md “The 5 Readiness Levels”, “How Scoring Works”, “The Technical Pillars”）
  • /readiness-report 命令运行该评估；/readiness-fix（文档中被引用，本轮未细读）自动修复未通过项；结果可通过 Readiness Reports API 查询（GET /api/organization/maturity-level-reports），返回逐条 {numerator, denominator, rationale}，附带 modelUsed {id, reasoningEffort} 和 droidVersion 溯源字段。（readiness-reports-api.md “Readiness Report Schema”）
• Mission 自我纠错循环：官方原文”a mission works, it runs user-facing QA testing against your application to validate each feature and self-correct as it goes”——明确依赖仓库具备可脚本化验证应用行为的能力，否则”the mission cannot reliably verify its own work.”（missions.md “For optimal outcomes”）
• Droid Shield 2.0 是本维度最扎实的硬证据——一条真实的微调流水线：
  • 基座模型 Qwen 3.6 35B A3B；两个 PEFT LoRA adapter——rank-16 的 “Risk”（捕捉扫描器的漏报），rank-64 的 “Downgrade”（清除扫描器的误报，输入前秘钥内容会被 mask 掉）。
  • 训练数据源自 Samsung 的 CredData（公开基准），经 LLM judge ensemble 重新打标（GPT-5.5 主评委，Opus 4.8 仲裁），并以 CredData 自带的 T/F/X 标签为基准校准，另加一批人工标注的”unknown”样本作为 grounding 示例。
  • Risk：5,000 条训练样本（40% 真实/40% 假阳/20% 未知），427/427 均衡评估集。Downgrade：6,776 条训练样本（69.7%/28.6%/1.6%），90/340 评估集（约 21% 真实，匹配生产环境基准率）。
  • 采用按仓库整体做 holdout（而非按文件级 holdout）的评估方式——原因是发现文件级 holdout 存在跨样本信息泄漏。
  • 结果：微调后的 adapter 在 ROC-AUC 上持平或超过 GPT-5.5/Opus 4.8（Risk 0.975 vs 0.961/0.948；Downgrade 0.845 vs 0.819/0.800），成本/延迟仅为后者的一小部分。
  • Downgrade 的阈值调优披露为显式的兑换率/效用函数：net utility = false_alarms_cleared - lambda * secrets_wrongly_cleared，扫过 lambda ∈ {1,2,5,10}，最终发布 lambda=5。
  • 模型权重 + tokenizer + 训练系统提示 + logprob 校准指导已在 Hugging Face 开源发布（factoryai/shield-risk-r16-c15、factoryai/shield-dg-r64-c15）。
  • 整条流水线是真实的eval 驱动、生产信号知情的模型改进闭环，明显区别于营销话术——披露了基于线上流量的基准率校准（仅聚合类先验，不使用原始会话数据作为训练行）、holdout 方法论，以及诚实的局限性说明（PR-AUC ~0.54”与 GPT-5.5 基本打平”、数据分布缺口）。（droid-shield-2.0-blog.md 全文）
• Automated Security Review 引用了具体的真实世界结果作为自身检测质量的验证信号：CVE-2026-42876（external-secrets Kubernetes operator 模板注入 → 任意 SA token 铸造）和一个 WorkOS Node SDK 的 HMAC 校验 bug，均由 Droid 发现并负责任地披露。（security-review.md “Real-world audits”）
• 未发现单个 agent 层面”从过往会话错误中学习并调整未来 prompt/权重”的自动化循环（这与 Shield 微调不同——后者是独立的离线 ML 流水线，不是会话内的自我修改机制）。未发现不等于确证不存在。

可观测性（日志 / trace 格式）

• Hook transcript 格式：每个会话是一个 .jsonl 文件，位于 ~/.factory/projects/<hash>/<session-id>.jsonl；每次 hook 调用收到的 JSON stdin payload 携带公共字段 session_id、transcript_path、cwd、permission_mode（off|spec|auto-low|auto-medium|auto-high）、hook_event_name，以及事件专属字段（如 PreToolUse/PostToolUse 的 tool_name、tool_input、tool_response）。这实际上就是该 harness 的结构化 trace schema。（hooks-reference.md “Hook Input” 及各”*-input”小节）
• 调试工具：hooks-reference.md 有完整的 “Debugging” 一节（Basic Troubleshooting、Advanced Debugging、Debug Output Example）——本轮仅确认标题与结构存在（通过目录），未读到底部细节（遗留缺口）。
• Analytics API（api.factory.ai/api/v1/analytics，需 Manager/Owner 角色，Bearer fk- API key）暴露组织级可观测性，覆盖 5 个端点：
  • /tokens —— 按日的 Factory Standard Credits（计费 token），含 input_tokens、output_tokens、cache_read_tokens、cache_write_tokens，可按 by_model/by_user 拆分。
  • /tools —— 按日的工具调用、MCP 使用、skills、slash command，以及 hook 调用次数（hooks_invocations、hooks_by_event 展示 event/matcher/command/count），以及 autonomy 比率百分位（autonomy_ratio_avg/p50/p90）与 tool_autonomy_level_ratio（各 auto_high/medium/low/manual 档位调用占比）。
  • /activity —— DAU/WAU/MAU，按客户端类型拆分（terminal-ui、web、non-interactive-cli）。
  • /productivity —— 文件操作 + git 活动。
  • /users —— 逐用户指标，分页，包含一个”Delegation Levels”概念（标题存在，本轮未读全）。 （analytics-api.md “Endpoints”, “Tool Usage” 响应示例）
• Readiness Reports API 同时充当 Agent Readiness eval 的可 CI 集成的可观测性面，每份报告附带 commit/branch/dirty-state 溯源（commitHash、branch、hasLocalChanges、hasNonRemoteCommits）以及模型溯源（modelUsed.id、modelUsed.reasoningEffort、droidVersion）——即每次自动化 eval 运行都能完整归因到 代码状态 + 模型配置 + CLI 版本 三元组。（readiness-reports-api.md “Report Object”）
• Droid Control 的 /verify 命令被明确定位为可观测性/证据生成工具：“Test whether a behavior claim is true and produce evidence either way”，附带”anti-fabrication rules”防止伪造证据，将 agent 定位为”investigator, not advocate”。这是把”防止虚假声明”作为一等可观测性关切的设计选择，而不仅是日志管道。（droid-control.md “What you get”, “/verify” 一节）

安全与权限（审批门、密钥管理）

两条独立的门控层，另加两个附加机制：

A. Autonomy Level（任务风险审批门）（auto-run.md）：

• 4 个级别：Off（仅只读工具+白名单）/ Low（+文件编辑、低风险命令）/ Medium（+可逆的工作区变更：安装、commit、mv/cp、build）/ High（+高风险：docker compose up、git push、migration）。
• 每个 Execute 命令/MCP 工具调用携带内在风险标签（low|medium|high）；风险 ⇐ 当前 Autonomy Level 时 Droid 自动运行，除非被 deny/blocklist 或 sandbox 检查覆盖。
• commandAllowlist/commandDenylist/commandBlocklist 设置：denylist 优先于 allowlist 但仍可人工批准；blocklist 是绝对的——不存在批准提示，即使在 --skip-permissions-unsafe 下也依然生效；命令解析逻辑会破解 bash -c "..."/绝对路径/引号绕过等尝试，先解析出实际被调用的程序再做匹配。
• 组织管理的设置在合并层级中优先级最高，可封顶成员可用的最大 Autonomy Level（例如组织上限 = Medium 时，High 会从 CLI 中完全隐藏）。
• Ctrl+L 循环切换等级；Shift+Tab 切换 Auto/Spec。

B. OS 级 Sandbox（执行隔离门，Beta）（sandbox.md）：

• 机制：macOS 上的 Seatbelt profile，Linux 上的 bubblewrap + seccomp，HTTP/SOCKS 代理做域名级网络过滤，Windows 通过 WSL2。
• 默认策略：文件读——除显式 denyRead 外全部允许；文件写——除 CWD 外全部拒绝（allowWrite 扩展许可范围，denyWrite 覆盖 allowWrite）；网络——除 *.factory.ai 外全部拒绝（allowedDomains 扩展许可范围）。
• 工具级命名的执行点：文件工具操作前的 checkFileAccess()；Execute 被包裹在 OS sandbox 内，网络流量经由”SRT’s filtering proxy”（SRT 是文档中披露但未展开定义的内部组件名）；FetchUrl 的 checkNetworkAccess()。文档明确坦承缺口：“main Droid process, MCPs and subagent are not isolated yet”。
• TUI 违规流程：即使在 Auto(High) 下也会中断，提供 3 个选项（Allow once / Allow always / Deny），网络提示经代理回调有 60 秒自动拒绝超时。
• 非交互（droid exec）模式：sandbox 违规自动拒绝、不做提示（不挂起），agent 收到拒绝消息并上报——这是为 CI 场景刻意设计的 fail-closed 行为。
• “Allow always”的持久化会写回 settings.json（加入 allowWrite，从 denyWrite/denyRead 移除，或按 3+ 段域名自动通配加入域名，如 registry.npmjs.org -> *.npmjs.org）。
• 组织管理的 denyWrite/denyRead 不可被用户的”Allow always”覆盖——只做并集合并，下游永不可移除。

C. 密钥管理：Droid Shield（确定性扫描器 + Shield 2.0 学习型门控）：

• v1（既有能力）：确定性 pattern/entropy 扫描器，对每次 commit/push 逐行扫描，命中可疑项即阻断。
• v2（本次调研的种子来源）：两个微调 LoRA 门控包夹在扫描器两侧——Risk 模型（扫描器沉默时介入，捕捉漏报，在给定 FPR 预算下优化召回）和 Downgrade 模型（扫描器已报警，秘钥片段在模型看到之前先被 mask，仅在高置信度时才清除误报）。完整 ML 细节见”自进化能力”节。关键安全设计点：Downgrade 模型架构上无法看到真实的秘钥值（进入其上下文窗口前已被 mask）——这是植入模型输入层面的刻意数据最小化/隐私控制，而非仅是策略层面的约束。
• 阈值是运行时可调、从 token logprob 读取的阻断概率截断值，无需重新训练即可重新配置——即安全/摩擦的权衡是一个部署期旋钮，而非训练期常量。
• 隐私设计：“Real sessions are never training rows… only aggregate class priors… calibrate curriculum and evaluation mix without ever exposing user content.”没有扫描命中数据实时流入 analytics；类先验来自对历史命中的缓存 judge 标签。

D. Automated Security Review（security-review.md、security-review-docs.md）：

• 基于 STRIDE 的威胁建模覆盖变更面 + OWASP Top 10/OWASP LLM Top 10 扫描，逐 PR 进行，带一个误报过滤步骤（“validates each candidate finding against the diff”），最终每个 PR 只发布一条去重的行内评论汇总。
• 深度、全仓库变体作为编排的 Mission 运行（/security-review deep audit），而非轻量级的逐 PR 扫描。
• 一次性安装通过 /install-code-review（自动检测 GitHub/GitLab，安装 GitHub App 或配置 GitLab，生成 CI workflow，开启一个合并 PR）。

E. Hooks 作为安全控制面：PreToolUse hook 可分类式地阻断/批准/修改工具调用；组织管理的 hooks（allowManagedHooksOnly: true）可强制组织内每台机器只运行厂商批准的 hook，忽略用户/项目级 hook——一个强中心化策略杠杆。文档明确警告 hook 以用户的实时凭证运行，恶意 hook 可外泄数据——“Always review your hooks implementation before registering them.”（hooks-guide.md 引言; hooks-reference.md “Org-managed hooks”, “Security Considerations”）

沙箱与执行隔离

两套不应混淆的独立系统：

1. 本地 OS 级 Sandbox（Seatbelt/bubblewrap/seccomp + 代理）——见上节 B。隔离的是用户自己机器上 本地 Droid CLI 进程的文件系统/网络可达范围。明确处于 Beta 阶段，且明确不完整（截至本次调研时，主进程/MCP/subagent 均未被沙箱化）。
2. Droid Computers——持久化的 远程 计算环境，一套完全不同的隔离模型（droid-computers.md）：
   • BYOM（自带机器：VPS/工作站/on-prem）vs Managed（Factory 托管的云 VM，默认规格 4 CPU / 8GB RAM / 6GB swap）。
   • 状态跨会话持久（区别于文档中提及但未深挖的”ephemeral cloud templates”——web/machine-connection/cloud-templates 是一个单独的、每会话即焚的概念）。
   • 披露的分步供给流水线：分配 VM → 创建带 sudo 权限的 factory-user → 写入环境配置/SSH 密钥/服务文件 → 安装 Droid 二进制 → 启动 SSH + Droid 守护进程服务。
   • 连接方式：droid computer ssh <name> 打开”a secure WebSocket tunnel through the daemon — no direct SSH port exposure required”，使用存储于 ~/.factory/.ssh/ 的专用 Ed25519 密钥对（与用户个人 SSH 密钥分离），每次连接时新鲜注入。
   • 官方坦诚披露的安全姿态：iptables 将入站限制到仅守护进程端口，但 factory-user 拥有免密 sudo，理论上可修改这些规则——若要硬边界，提供”relay mode”，将全部流量经由 Factory 的中继服务路由，零暴露公网端口（BYOM 始终可用，Managed 可组织级配置）。
   • 托管 VM 上禁用 root 登录 + 密码认证（SSH 加固）。
3. Mission worker 隔离：文档暗示（“Launches recorded sessions on the baseline and candidate branches in parallel using worker subagents”），但未针对 Mission worker 披露超出上述两套系统之外的额外隔离细节。

与模型的协同设计

• Factory Router（factory-router.md、web-factory-router.md）是本维度信息量最大的产物：跨一批前沿模型+高效模型池的自动逐会话模型选择，带 会话中途升级机制——“If the selected model struggles to complete the task, Factory Router moves the session to a more capable model”，即 harness 对任务进度的监控足以在会话进行中触发模型切换，而不仅是会话开始时一次性选定。
  • 官方声称的结果：在 Terminal-Bench 2 / Legacy-Bench 上分别以 Claude Opus 4.7 的 99%/96% 通过率换取 20-25% 的 token 花费降低；同时披露了”每次成功运行的成本”（而非仅”每次会话的成本”，为 80.5%/78.0% of Opus）——专门用于排除”提早放弃难会话”这种对成本指标的博弈。
  • 可靠性层：provider 故障转移、面向企业的专属 TPM（每分钟 token 数）预留，以及明确提及**“US-hosted open-source models”**作为路由目标类别——暗示 Factory 自营或代理托管开源权重模型作为路由的一等目标，而非仅面向闭源前沿 API。
  • 企业管理员可提供路由指导（自由文本，“describe workflow patterns, codebase areas, toolchains, model preferences”）来影响自动选型——这是一个自然语言配置面，而非规则 DSL。
  • 披露了显式的 Pareto 前沿方法论：扫过路由器的激进程度，从”always frontier”到”maximally cheap”，绘制通过率 vs 会话成本曲线；文档记录了越过某个”拐点”后通过率会骤降（测试过的最激进设置：Terminal-Bench 2 上以 56% of Opus 成本换取 81% 通过率；Legacy-Bench 上 30%/49%）——Factory 刻意选择在拐点之前的平坦段上线，这是一个披露且有理据的运营点，而非仅仅是宣称的数字。
• Mixed Models（mixed-models.md）配置允许不同 subagent/任务绑定不同模型——每个 Custom Droid 的 frontmatter model: 字段可以是 inherit、内置模型的显式 ID、或 custom:<id>（BYOK）。reasoningEffort（low|medium|high）是单独可调的 per-subagent 字段，仅在 model 非 inherit 时才有意义。
• 模型专属的工具兼容 shim 被硬编码进 harness：“When using Edit with OpenAI models, ApplyPatch is automatically included for compatibility”——即 harness 知道 OpenAI 模型需要不同的编辑工具调用约定，会静默地同时注册两个工具；当 model: inherit 时，两者都被防御性地启用以覆盖任意 provider。（custom-droids.md “Tool categories → concrete tools” 表格脚注）
• BYOK（byok.md）允许组织指向自托管/自定义 provider 的模型；在 custom droid 的模型 ID 中引用为 custom:<model-field-value>（必须匹配 BYOK 配置的 model 字段，而非 model_display_name——一个文档中明确指出的具体易踩坑点）。
• Droid Shield 2.0 的模型选型本身就是一个披露了理据的协同设计决策：选择 Qwen 3.6 35B A3B 的官方理由是”due to its coding strength, reasoning capabilities, and improved cost/latency in comparison to the frontier”，并明确表达了对更小模型（Nemotron 3 Nano）的前瞻兴趣——即 Factory 把”哪个基座模型能获得生产级微调席位”当作一个主动的、有理据的、成本敏感的决策，而非默认选最大的可用模型。

轨迹利用（session/trajectory 是否反哺训练/评测）

• 有，但范围很窄且带有明确披露的隐私护栏——最清晰的证据仍是 Droid Shield 2.0：
  • 真实用户会话从不作为训练行（“Real sessions are never training rows”）。
  • 真正被使用的是：聚合的、采样的类先验，跨越”足够多不同会话以防止任何可识别信息”，仅用于校准训练/评估数据的配比（例如匹配文件类型分布——ts/py/md/tsx——以及将 downgrade 评估集的约 21% 真实秘钥基准率对齐到”我们采样得到的聚合生产基准率”）。这是轨迹衍生的统计量，而非轨迹衍生的内容，反哺进 eval 设计。
  • 官方原文：“We do not store any scanner or secret detections in our analytics; class priors come from cached judge labels over historic hits, not a live stream.”（droid-shield-2.0-blog.md “Data”, “Considerations and limitations”）
• Analytics API 将轨迹衍生的聚合数据暴露给组织管理员（工具调用计数、autonomy 比率分布、按事件/matcher 的 hook 调用计数）——这是轨迹数据流回给客户自己的仪表盘，而非流向 Factory 用于模型训练，且明确限定组织范围/权限（仅 Manager/Owner 角色）。
• Readiness Reports 是纵向、可跨时间比较的（每个仓库的历史报告分页列表），被明确定位为 CI/仪表盘/告警的输入——这是 eval 轨迹前向反哺自动化修复（/readiness-fix，被提及但未深挖）与门控（Missions 需要 Level 4+）。
• AutoWiki 的增量 diff 机制是一种”代码轨迹复用”（而非”agent 行为轨迹复用”）：每次再生成读取上一版 wiki 存储的 commit-hash 元数据来计算 diff，只重新处理变化的页面——这是代码状态轨迹的复用，不是 agent 行为轨迹的复用。
• 未发现原始用户会话 transcript 被用于微调 Factory 自家 coding 模型的证据（区别于范围很窄的 Shield 秘钥检测分类器）。未发现不等于确证不存在，仅为未被披露。

与同类 harness 的关键差异（1-3 条，可以先留一句概述，后续 synthesis 阶段会做跨 harness 对比）

• 与 Claude Code 类似（同为闭源分发），但 Factory 在”官方文档披露深度”上走得更远——函数名级别的权限检查点披露（checkFileAccess()/checkNetworkAccess()）、完整的 hook JSON schema、以及一整条可复现的 LoRA 微调工程细节（Shield 2.0），使其在”无源码”harness 中调研深度接近源码级。
• 长期记忆的解法（AutoWiki：多 agent 生成、增量 diff、四端持久化、代码提交式而非向量存储式）与常见的 RAG-记忆层设计路线明显不同，值得作为一种独立的记忆系统范式记录。
• Factory Router 的”会话中途模型升级”+ 显式披露的 Pareto 拐点方法论，是本次调研中少见的、把模型路由的成本/质量权衡讲清楚到具体数字和方法论层面的案例（多数同类 harness 只笼统宣称”智能路由”）。
• 跨 harness 对比留待 synthesis 阶段展开。

原始源码定位

• repo: github.com/Factory-AI/factory（docs-only，无应用源码；Droid CLI 本身闭源，无公开仓库）
• commit/version analyzed: fdf8712a06b566cbcbd3920ae01e52be3f462ab9（2026-07-01, “docs: add CLI changelog entry for v0.162.0 (#1268)”）；CLI 版本推断约 v0.162.0
• 关键文件列表（相对路径，均为 docs.factory.ai / factory.ai/news 页面，非源码）：
  • docs/reference/hooks-reference — 完整 hook schema，agent-loop + 可观测性核心来源
  • docs/cli/configuration/sandbox — OS 级沙箱、逐工具权限检查函数名
  • docs/cli/user-guides/auto-run — Autonomy Level、allow/deny/blocklist
  • docs/cli/configuration/custom-droids — Subagent 定义、工具类别映射
  • docs/cli/configuration/mcp — MCP 注册协议
  • docs/cli/configuration/skills — Skill 系统
  • docs/cli/configuration/agents-md — AGENTS.md 约定
  • docs/cli/features/missions — Mission 编排
  • docs/cli/droid-exec/overview — 无头执行模式全 CLI 参数
  • docs/cli/features/droid-computers — 远程计算环境
  • docs/cli/features/droid-control — 终端/浏览器自动化插件
  • docs/reference/analytics-api — 组织级观测 API
  • docs/reference/readiness-reports-api — Agent Readiness 报告 schema
  • docs/web/agent-readiness/overview — Agent Readiness Model
  • factory.ai/news/droid-shield-2-0 — Droid Shield 2.0 微调流水线（博客，非 docs）
  • factory.ai/news/factory-router — Factory Router（博客）
  • factory.ai/news/wiki — AutoWiki（博客）
  • factory.ai/news/automated-security-review — 自动化安全审查（博客）

一手源存档（sources/）

全部保存于 /Users/zhao/projects/self-wiki/ai-research/sources/harness/factory-ai/（29 个文件，508KB，索引见该目录下 NOTES.md）：

• NOTES.md — 本次调研的完整过程记录与逐维度笔记（源材料）
• droid-shield-2.0-blog.md — Droid Shield 2.0 完整 ML 方法论博客
• security-review.md / security-review-docs.md — 自动化安全审查（博客 + docs）
• factory-router.md / web-factory-router.md — Factory Router（博客 + docs）
• software-factory.md / web-software-factory.md — Software Factory 产品定位（博客 + docs）
• wiki.md — AutoWiki 博客
• docs-home.md — docs 首页（导航树）
• sandbox.md — OS 级沙箱
• auto-run.md — Autonomy Level
• hooks-guide.md / hooks-reference.md — Hooks 快速指南 + 完整 schema
• custom-droids.md — Custom Droids（subagent）
• mcp.md — MCP 配置
• skills.md — Skill 系统
• agents-md.md — AGENTS.md 约定
• missions.md — Factory Missions
• droid-exec.md — 无头执行模式
• droid-computers.md — 远程计算环境
• droid-control.md — 终端/浏览器自动化插件
• mixed-models.md — 混合模型配置
• byok.md — Bring-your-own-key
• settings.md — settings.json schema
• cli-reference.md — 完整 CLI 参考
• analytics-api.md — Analytics API
• readiness-reports-api.md — Readiness Reports API
• agent-readiness.md — Agent Readiness Model

遗留缺口（供后续补充调研参考）：hooks-reference.md 的 “Working with MCP Tools”、“Security Considerations” 全文、“Debugging” 高级部分仅确认标题未读全文；mixed-models.md/byok.md/settings.md/cli-reference.md 仅抽读；docs/cli/features/wiki/overview（AutoWiki 完整文档）未单独抓取；droid-sdk-typescript/droid-sdk-python/droid-action/factory-plugins/eslint-plugin 等关联仓库仅确认存在未克隆细读；未尝试访问需登录的 app.factory.ai 产品本身。