项目定位与目标场景

Tako VM 解决的是"AI Agent 产出的代码片段如何在生产环境中安全执行"的问题。它的运行模式与传统的 Celery/RQ 等任务队列在概念上类似，但侧重点不同：

• 容器化执行：每个任务在独立的 Docker 容器中运行，依赖通过 job type 预装 资料来源：tako_vm/job_types.py:1-15
• 审计级记录：每次执行生成 ExecutionRecord，包含代码哈希、输入哈希、参数哈希、退出码、资源使用、错误 JSON 等字段 资料来源：tako_vm/models.py:1-50
• 幂等性支持：通过 idempotency_key 唯一索引保证重复提交返回相同结果 资料来源：tako_vm/storage.py:25-40
• 版本化任务类型：基于内容哈希（SHA256）计算 digest，支持 @v1.0.0 形式的语义版本别名 资料来源：tako_vm/version.py:30-50

项目通过 mkdocs.yml 组织文档，分为 Getting Started、Architecture、API Reference、Guide 等板块 资料来源：mkdocs.yml:25-50，说明它面向自部署的工程团队而非托管服务用户。

系统架构

Tako VM 采用经典的服务端 + 异步 Worker 架构，对外暴露 REST API 和 Python SDK 两种入口。系统组件及数据流如下：

flowchart LR
    Client[客户端 / SDK] -->|HTTP / send| API[FastAPI 服务端<br/>tako_vm/server/app.py]
    API -->|写入| DB[(PostgreSQL<br/>execution_records)]
    API -->|入队| Queue[任务队列]
    Queue -->|取任务| Worker[Worker Pool]
    Worker -->|docker run| Container[隔离容器]
    Container -->|结果写回| DB
    Container -->|stdout/stderr| Security[安全模块<br/>sanitize + cap]
    Security -->|记录| API
    API -->|查询/回调| Client

关键模块职责：

服务端提供分页接口（limit 上限 1000）与 ?view=full 扩展视图，包含 artifacts、lineage 等信息 资料来源：tako_vm/server/app.py:1-40。

核心执行模型

Tako VM 的执行流程与社区中常被误解的"本地函数"模式有本质区别，这一点在 issue #39 中被特别指出。Python SDK 的 @tako.send() 装饰器不会在本地执行函数体，而是：

1. 序列化函数源码与参数（按类型提示做序列化）
2. 入队到 execution_records 表，分配 idempotency_key
3. 拉取：Worker Pool 从队列中取出 pending 任务
4. 运行：在匹配的 job type 容器中执行，捕获 stdout/stderr/exit_code
5. 归档：资源使用、错误结构化字段、artifacts 全部入库

需要特别注意的是 pending 与 queued 在 API 文档中存在混用（issue #29）。从源码看，status 字段是记录级状态，队列状态由后台调度状态决定，二者需在文档中明确区分 资料来源：tako_vm/models.py:30-60、`tako_vm/storage.py:20-40]()。

预置的 default、data-processing、ml-inference、test-with-secrets 等 job type 来自 tako_vm/job_types.json，其中 test-with-secrets 显式演示了环境变量注入模式 资料来源：tako_vm/job_types.json:1-80。

安全模型与已知风险

Tako VM 在 tako_vm/security.py 中实现了多层防护：64KB 的 stdout/stderr 截断、敏感路径与容器 ID 的正则脱敏、环境变量键值校验、pip 需求白名单等 资料来源：tako_vm/security.py:1-30。同时 validate_docker_image、validate_env_key 等函数在容器构建阶段阻止危险输入 资料来源：tako_vm/execution/builder.py:20-35。

然而，安全是当前文档与实现的薄弱环节，与社区关切高度相关：

• CRITICAL 风险：环境变量可通过容器内 /proc/self/environ 被运行时代码读取（issue #40）。test-with-secrets job type 仍以明文存储 API_KEY，说明当前未做加密或 secret mount 隔离。
• 缓解文档未落地：docs/security/mitigations.md 列出了 Phase 1–4 路线图，但多数条目尚未实现（issue #32）。开发者不应把它当作"已修复"的功能。
• CLI 文档错位：旧文档引用了不存在的 tako-vm build job-type <name> 与 python -m tako_vm.container_builder --build-all 命令（issue #30、#37）。实际构建入口是 tako-vm setup 或经由 ContainerBuilder 类 资料来源：tako_vm/cli.py:1-50tako_vm/execution/builder.py:1-30]()。

实践建议：在将 Tako VM 投入生产前，始终假设环境变量在容器内可被任意读取，把敏感凭据放到 Vault 等外部系统并通过短期 token 注入。

See Also

• 入门：安装、Quick Start、配置
• API：REST API、Python SDK
• 指南：Job Type 与环境、自定义库
• 部署：生产部署、扩缩容、运维 Runbook（待补）

概述与核心组件

Tako VM 是一个面向 Python AI 代理的任务队列基础设施，其核心思路是把"运行环境预定义 + 代码序列化提交 + 容器化隔离执行"组合成一套可审计的批处理系统。包级别的公开 API 由 tako_vm/__init__.py 统一导出，涵盖 JobTypeRegistry、ExecutionRecord、ResourceUsage、Artifact、JobVersion 等模型与异常类型。

系统的关键抽象包括：

• JobType：预定义容器模板，决定依赖、Python 版本、资源限制、是否启用 GPU、是否启用 session 等（资料来源：tako_vm/job_types.py）。
• ExecutionRecord：审计级别的执行记录，持久化到 PostgreSQL，包含 code_hash、input_hash、params_hash、exit_code、resource usage 等字段（资料来源：tako_vm/models.py）。
• VersionManager：基于内容哈希为 JobType 计算 digest，支持按 sha256:... 摘要或语义化 tag 查询版本（资料来源：tako_vm/version.py）。
• REST API + Python SDK：通过 tako-vm server 启动 FastAPI 服务，对外暴露 /executions/{id} 等接口（资料来源：tako_vm/server/app.py）。

任务提交与执行模型

社区多次反馈 SDK 的 send() 执行模型说明不足（参见 Issue #39）。需要特别强调：装饰器修饰的函数体不会在本地执行，而是被序列化（基于类型提示做参数/返回值的编解码）后投递到服务端，再由 worker 在 Docker 容器中运行。因此类型提示在这里承担双重职责：既是静态检查，也驱动了跨进程的数据序列化。

执行生命周期在存储层有明确体现。execution_records 表通过 status 索引加速轮询，并通过 (status, job_type, created_at DESC) 复合索引支撑高效分页（资料来源：tako_vm/storage.py）。客户端可通过 GET /executions/{id} 查询单条记录，或通过分页接口 GET /executions?view=full 拉取包含 artifacts、resource_usage、code_hash 等的完整响应（资料来源：tako_vm/server/app.py）。

需要区分两个看似相近的状态：

由于历史文档将两套状态混用（参见 Issue #29），轮询时建议同时关注 status 与 created_at 的组合，避免因状态命名混淆而误判任务进度。

JobType 定义、构建与版本化

每个 JobType 是一段 JSON/YAML 配置，描述如何构造 Docker 镜像。tako_vm/job_types.json 中提供了 default、data-processing、ml-inference 等示例，其中 data-processing 预装 pandas、numpy 并设置 memory_limit=1g、cpu_limit=2.0（资料来源：tako_vm/job_types.json）。

构建流程由 tako_vm/execution/builder.py 中的 ContainerBuilder 承担：generate_dockerfile() 会校验 python_version、requirements、environment 等字段，调用 validate_pip_requirement、validate_env_key、validate_env_value 等安全工具后再生成 Dockerfile。版本摘要由 VersionManager.compute_digest() 计算，纳入哈希的字段包含 requirements、python_version、base_image、environment、shared_code、session_enabled、GPU 配置等（资料来源：tako_vm/version.py），这保证只要"影响镜像内容"的字段变化，就会得到新的 sha256:... 摘要。

下面用一个架构图概括从配置到执行的端到端流程：

flowchart LR
    A[JobType 配置] --> B[VersionManager.compute_digest]
    B --> C[sha256 摘要]
    A --> D[ContainerBuilder.generate_dockerfile]
    D --> E[Docker 镜像 image_ref]
    C --> F[execution_records]
    E --> F
    G[SDK send / REST POST] --> F
    F --> H[Worker 拉起容器]
    H --> I[stdout / stderr / artifacts]
    I --> J[ResourceUsage + ErrorType]

配置、安全与常见误区

服务端配置通过 YAML 加载，搜索路径依次为 ./tako_vm.yaml、config/tako_vm.yaml、~/.tako_vm/config.yaml、/etc/tako_vm/config.yaml（资料来源：tako_vm/config.py）。CLI 支持 server、dev up/down/status、status、validate、config、setup、version 等子命令（资料来源：tako_vm/cli.py）。

关于安全与文档偏差的几点提醒：

1. 环境变量暴露：docs/security/mitigations.md 把通过 /proc/self/environ 读取 env 标记为 Priority: CRITICAL（参见 Issue #40）。即便 JobType.environment 只是传给容器的环境变量，也应避免写入 API key、数据库密码等敏感值；优先使用服务端 secret store。
2. 不存在的 CLI 命令：tako-vm build job-type <name> 在多处文档中被引用，但 tako_vm/cli.py 中并无 build 子命令（参见 Issue #30）。当前构建路径应通过 ContainerBuilder 的 Python API 或 tako-vm setup 触发。
3. 不存在的 python -m 命令：python -m tako_vm.execution.builder --init-defaults all 与 python -m tako_vm.container_builder --build-all 均无对应实现（参见 Issue #37），请勿照搬旧文档。
4. 先决条件缺失：Docker 镜像构建并非"可选"，提交任务前必须先有可用的 image_ref；同时 PostgreSQL 需在 quickstart 之前就位（参见 Issue #31）。

安全模块本身已经做了不少兜底：security.py 中的 SANITIZE_PATTERNS 会把临时目录、用户家目录、容器 ID、IP 等敏感信息从错误消息中替换为占位符（资料来源：tako_vm/security.py）。结合上述限制与模型层的 ErrorType 字面量（涵盖 oom、segfault、execution_timeout 等分类），可以在排查失败原因时既保留足够信号，又避免泄漏宿主与容器拓扑信息。

参见

• 架构总览
• 安装与先决条件
• 快速开始
• 配置参考
• REST API
• Python SDK
• 运行环境与 JobType 指南

概述

Tako VM 是一个面向 Python AI 代理的作业队列基础设施，其安全模型围绕「容器化隔离 + 入口/出口内容净化 + 资源配额」三层展开。生产运维层面，系统通过 CLI 与 REST API 提供配置校验、构建、状态查询、版本注册等能力，但部分文档与 CLI 仍存在不一致（详见 Issue #30 与 Issue #37），运维人员需要按本文档核对当前实际可用的命令集合。

一、安全模型核心

1.1 错误信息与输出净化

tako_vm/security.py 定义了 SANITIZE_PATTERNS 列表，对错误信息中的敏感路径与标识符进行脱敏处理：

• 临时目录：/tmp/job-*、/var/folders/*
• 用户主目录：/Users/...、/home/...
• 容器内部路径：/app/***
• 内网 IP：172.x.x.x、10.x.x.x、192.168.x.x
• Docker 容器 ID：64 位或 12 位十六进制串统一替换为 <container-id>

同时 DEFAULT_MAX_STDOUT_BYTES 与 DEFAULT_MAX_STDERR_BYTES 默认为 64 KB，对执行产物的 stdout/stderr 实施大小上限，避免容器把任意大小输出写回主机。

tako_vm/models.py 进一步规范了 ErrorType 枚举，覆盖 oom、cancelled、segfault、abort、arithmetic_error、bus_error、pipe_error 等信号级错误，以及 startup_timeout / execution_timeout 两个阶段级超时。这些值在记录 execution_records 时作为规范化字段使用，便于死信队列的统计与告警（REST 端点 /dlq/stats 即依赖该规范化）。

1.2 已知安全风险

社区文档指出，通过 /proc/self/environ 读取环境变量 被标记为 Priority: CRITICAL（Issue #40）。在 tako_vm/job_types.json 的 test-with-secrets 示例中，容器以环境变量形式注入了 API_KEY 与 DATABASE_URL，这正是上述风险的演示场景。运维人员应在 JobType.environment 中避免写入长期凭据，改用外部 secret 注入或短时效 token。

1.3 输入校验

ContainerBuilder.generate_dockerfile 在生成 Dockerfile 之前调用 validate_python_version、validate_env_key、validate_env_value、validate_pip_requirement、validate_docker_image 等函数进行预校验，校验失败抛出 BuildError。这保证镜像构建阶段即拒绝恶意或畸形配置。

二、容器执行沙箱

JobType 数据类（tako_vm/job_types.py）是沙箱配置的来源，关键字段如下：

tako_vm/config.py 中的 ContainerLimits 进一步约束文件描述符（nofile_soft/hard）与进程数（nproc_soft），使用 Pydantic 字段约束 ge=64, le=65536 等上下界，防止运维误配导致容器逃逸或主机耗尽资源。

network_enabled 默认 False 意味着容器在大多数场景下无法出网，这是阻断数据外泄与依赖混淆攻击的关键防线。session_enabled 用于启用跨多次调用的会话容器，开启后需要更严格的清理策略。

三、生产运维

3.1 可用的 CLI 子命令

tako_vm/cli.py 中实际存在的子命令为：server、dev (up/down/status)、status、validate、config [--json] [--show-defaults]、setup、version。setup 拉取执行器镜像并验证 Docker 可用性。没有 tako-vm build job-type 子命令，构建动作必须通过 REST API /job-types/{name}/build 触发（tako_vm/server/app.py），该端点会调用 ContainerBuilder.build() 并通过 VersionManager.register_version() 写入 job_versions 表。

3.2 版本与幂等

VersionManager.compute_digest()（tako_vm/version.py）基于 requirements、python 版本、基础镜像、环境变量、会话/GPU 配置等序列化后取 SHA256，保证「相同配置 + 相同依赖 ⇒ 相同 digest ⇒ 可复现构建」。storage.py 在 execution_records 上对 idempotency_key 建立 UNIQUE 部分索引，配合调用方传入的幂等键实现「重复请求同结果」，这是生产环境避免重复扣费或重复副作用的核心机制。

3.3 运行状态查询

• GET /pool/stats —— 当前 worker 池统计
• GET /dlq/stats —— 死信队列聚合
• GET /dlq?error_type=... —— 分页列出死信记录
• GET /executions?view=full —— 审计级记录（含 artifacts、资源用量、内容哈希与父子链路）

3.4 待补齐的运维 Runbook

社区已记录到 docs/deployment/scaling.md 将容器池、分布式 worker、S3 存储等列为「Planned」但未区分现状（Issue #34），同时缺乏熔断器跳闸、DLQ 积压、Docker 守护进程崩溃等场景的 runbook（Issue #33）。生产部署前，运维团队应自行编写：①熔断跳闸后的隔离与恢复步骤；②DLQ 复放/清空流程；③Docker 守护进程崩溃的健康检查与告警阈值。

四、API 中作业状态字段

REST 文档中存在 pending（队列状态）与 queued（记录状态）混用的问题（Issue #29）。轮询 /executions/{id} 的客户端应同时识别两值，并结合 created_at 排序判断作业是否已离开调度层。

See Also

• 配置参考
• REST API 参考
• Job Types 与执行环境
• 部署指南

1. Python SDK 客户端

tako_vm/sdk/__init__.py 是 SDK 的公共入口，导出 send、send_raw、configure、list_job_types、get_job_type、TakoVM、ExecutionResult、TakoVMError、ExecutionError 与 ValidationError 资料来源：tako_vm/sdk/__init__.py:1-31。

send 是装饰器，其核心语义需要特别强调：被装饰的函数体不会在本地运行——它会被序列化为源码与类型提示，投递到 Tako VM 服务器，由指定 Job Type 的容器远程执行（社区 issue #39 指出此执行模型常被误解）。send_raw 则允许以原始载荷提交代码片段，绕过装饰器的类型推断。configure 用于设置服务端点与 API Key 等全局参数；list_job_types 与 get_job_type 用于查询已注册的 Job Type 清单 资料来源：tako_vm/sdk/__init__.py:1-31。

sequenceDiagram
    participant U as 用户代码
    participant SDK as Tako VM SDK
    participant API as REST API
    participant DB as PostgreSQL
    U->>SDK: 装饰 send(fn)
    SDK->>SDK: 序列化 fn 源码 + 类型提示
    SDK->>API: POST /executions
    API->>DB: 插入 execution_record (status=queued)
    API-->>SDK: 返回 execution_id
    SDK-->>U: 立即返回
    Note over U,DB: 容器异步执行
    U->>API: GET /executions/{id}
    API->>DB: 查询
    DB-->>API: record
    API-->>U: ExecutionRecord (status=running|completed|failed)

SDK 抛出的异常层次为 TakoVMError → SDKExecutionError（向后兼容别名 ExecutionError）→ ValidationError 资料来源：tako_vm/__init__.py:1-44。

2. REST API 端点

HTTP 服务由 tako_vm/server/app.py 提供。核心端点包括：

• POST /executions — 提交一次代码执行
• GET /executions — 列出执行记录，支持 status、job_type、limit、offset 过滤
• GET /executions/{execution_id} — 获取单条记录，附加 ?view=full 可返回包含 artifacts、content hashes 与 lineage 的完整载荷

limit 参数最大为 1000，超出时服务端按 min(limit, 1000) 截断并通过 has_more 标志返回下一页是否存在 资料来源：tako_vm/server/app.py:1-200。针对社区 issue #29 提出的 pending 与 queued 状态混淆：queued 是数据库记录层（已落库、等待调度）状态，pending 是队列层（worker 尚未拉取）状态；二者可在轮询生命周期中先后出现，开发者应根据业务语义选择合适的轮询点。

3. 配置与 CLI 实际可用命令

tako_vm/config.py 使用 Pydantic 进行严格边界校验，子模型通过 model_config = {"extra": "forbid"} 拒绝未声明字段 资料来源：tako_vm/config.py:1-60。配置文件按以下顺序搜索：./tako_vm.yaml → ./config/tako_vm.yaml → ~/.tako_vm/config.yaml → /etc/tako_vm/config.yaml 资料来源：tako_vm/config.py:1-30。

JobType（tako_vm/job_types.py）描述一个容器化执行环境：requirements、python_version、base_image、shared_code、environment、memory_limit、cpu_limit、timeout、startup_timeout、network_enabled、session_enabled 与 gpu 子字典 资料来源：tako_vm/job_types.py:1-80。仓库提供的示例 tako_vm/job_types.json 内置了 default、data-processing、ml-inference 以及一个故意暴露明文密钥的 test-with-secrets——后者仅作为风险演示，不应在生产中启用（社区 issue #40 已警示环境变量可能通过 /proc/self/environ 泄露）资料来源：tako_vm/job_types.json:1-200。

CLI 实际可用的子命令（tako_vm/cli.py）为：server、dev {up,down,status}、status、validate [path]、config [--json] [--show-defaults]、setup、version 资料来源：tako_vm/cli.py:1-100。注意：文档中曾引用的 tako-vm build job-type <name>（社区 issue #30）以及 python -m tako_vm.execution.builder（社区 issue #37）目前不存在，请改用 tako-vm setup 拉取执行镜像后由服务端按需构建 Job Type。

4. 数据模型、版本与安全约束

执行记录由 ExecutionRecord（tako_vm/models.py）承载；ResourceUsage 约束 max_rss_mb ≤ 1TB、cpu_time_ms 与 wall_time_ms ≤ 24 小时 资料来源：tako_vm/models.py:1-100。Artifact 的 name 字段禁止包含路径分隔符以防止目录穿越，storage_key 长度上限 1024 资料来源：tako_vm/models.py:100-200。

JobVersion 通过 SHA256 内容哈希保证可复现构建，full_ref 形如 name@sha256:<前 12 位摘要>，对应镜像以 tako-vm-<job_type>@sha256:... 引用 资料来源：tako_vm/models.py:200-280、tako_vm/version.py:1-80。

错误分类由 ErrorType 字面量定义，区分 startup_timeout/execution_timeout 与信号类（oom、cancelled、segfault、abort、arithmetic_error、bus_error、pipe_error） 资料来源：tako_vm/models.py:280-320。tako_vm/security.py 的 SANITIZE_PATTERNS 会在错误消息中替换临时目录、家目录、内网 IP 与容器 ID，避免敏感路径泄露到响应里 资料来源：tako_vm/security.py:1-40。PostgreSQL 表 execution_records 还会为 idempotency_key 建立唯一索引，使重复提交得到去重 资料来源：tako_vm/storage.py:1-80。

See Also

• 架构总览
• REST API
• Python SDK
• 配置参考
• 安全缓解措施

Pitfall Log / 踩坑日志

项目：las7/takovm

摘要：发现 18 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Docs: add end-to-end example application。

1. 安装坑 · 来源证据：Docs: add end-to-end example application

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Docs: add end-to-end example application
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_78a96aee28384d93b96002b77e6027ea | https://github.com/las7/TakoVM/issues/38 | 来源类型 github_issue 暴露的待验证使用条件。

2. 安装坑 · 来源证据：Docs: add operational runbooks for production deployment

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Docs: add operational runbooks for production deployment
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_1702731d27b44ab483e81e1e39003db1 | https://github.com/las7/TakoVM/issues/33 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：Docs: getting-started missing prerequisites checklist

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Docs: getting-started missing prerequisites checklist
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_31b37ccb63c64ad89eb926be535f46d5 | https://github.com/las7/TakoVM/issues/31 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 安装坑 · 来源证据：Docs: non-existent python -m CLI commands in production.md and environments.md

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Docs: non-existent python -m CLI commands in production.md and environments.md
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f10bb15a58f541479f103040c56f2845 | https://github.com/las7/TakoVM/issues/37 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 安装坑 · 来源证据：Docs: tako-vm build command referenced but doesn't exist in CLI

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Docs: tako-vm build command referenced but doesn't exist in CLI
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_a81c31adb886463ba3fe59c976ca6534 | https://github.com/las7/TakoVM/issues/30 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

6. 能力坑 · 来源证据：Docs: scaling.md lists planned features without clarifying current state

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：Docs: scaling.md lists planned features without clarifying current state
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_81231681c1d64897a42c17e87568c065 | https://github.com/las7/TakoVM/issues/34 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

7. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | hn_item:48431257 | https://news.ycombinator.com/item?id=48431257 | README/documentation is current enough for a first validation pass.

8. 运行坑 · 来源证据：Docs: SDK send() execution model poorly explained

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Docs: SDK send() execution model poorly explained
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_14c9181db25446ecaa58b6cfef944ab4 | https://github.com/las7/TakoVM/issues/39 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

9. 运行坑 · 来源证据：Docs: clarify pending vs queued job status

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Docs: clarify pending vs queued job status
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_726651d2543a41fcb2b12eacce59f8eb | https://github.com/las7/TakoVM/issues/29 | 来源类型 github_issue 暴露的待验证使用条件。

10. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | hn_item:48431257 | https://news.ycombinator.com/item?id=48431257 | last_activity_observed missing

11. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | hn_item:48431257 | https://news.ycombinator.com/item?id=48431257 | no_demo; severity=medium

12. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | hn_item:48431257 | https://news.ycombinator.com/item?id=48431257 | no_demo; severity=medium

13. 安全/权限坑 · 来源证据：Add optional egress proxy for dependency installs

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add optional egress proxy for dependency installs
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_8dcc73f80c184253a4646f4293c8e38c | https://github.com/las7/TakoVM/issues/15 | 来源类型 github_issue 暴露的待验证使用条件。

14. 安全/权限坑 · 来源证据：Disable runtime dependency installs by default

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Disable runtime dependency installs by default
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_17ba6c128eaa4f4996dcd06c7d309f2b | https://github.com/las7/TakoVM/issues/14 | 来源类型 github_issue 暴露的待验证使用条件。

15. 安全/权限坑 · 来源证据：Docs: mitigations.md reads as issue tracker, not documentation

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Docs: mitigations.md reads as issue tracker, not documentation
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_169ec35f009e4f86a8b322531f643e96 | https://github.com/las7/TakoVM/issues/32 | 来源类型 github_issue 暴露的待验证使用条件。

16. 安全/权限坑 · 来源证据：Docs: quickstart missing security warnings for env vars and /proc exposure

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Docs: quickstart missing security warnings for env vars and /proc exposure
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_e70e50033ee2425c80d460b507c69efd | https://github.com/las7/TakoVM/issues/40 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

17. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | hn_item:48431257 | https://news.ycombinator.com/item?id=48431257 | issue_or_pr_quality=unknown

18. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | hn_item:48431257 | https://news.ycombinator.com/item?id=48431257 | release_recency=unknown