UpToCode

UpToCode

UpToCode 是一款面向 Python 和 TypeScript Agent 应用的设计时架构质量扫描器。它能发现缺失的执行边界、运行预算、审批、验证、弹性控制、评估和可观测性；解释相关证据；并为 Codex 生成由审批驱动的计划，而不会重写源代码。

该产品刻意聚焦于比通用 Agent 安全扫描器更窄的范围。1.7 版可识别 OpenAI、Anthropic、CrewAI、PydanticAI、LlamaIndex、LangGraph、保守识别的自定义 Python/TypeScript 循环，以及上下文存在无界增长的正面证据。静态扫描在本地离线运行。可选的 GPT‑5.6 判断始终明确、受限、经过脱敏，并且受代码共享门控控制。

Python 发行包、导入包和命令的名称均为 uptocode。1.0.0 版 是已发布的基线；此源代码树已准备为 1.10.0，供由运营方门控的 Batch 3 发布序列使用。

在本地安装

UpToCode 需要 Python 3.11 或更高版本。从 PyPI 安装经过验证的 1.0 版：

python -m pip install "uptocode==1.0.0"
uptocode --help

对于仓库开发，请使用可编辑测试环境：

python -m pip install -e ".[test]"
uptocode --help

所有常规测试均使用模拟，且离线运行：

python -m pytest -q
python scripts/acceptance.py

评审测试构建

仓库和软件包均为公开内容。完整的离线测试构建不需要托管凭据，也不需要调用付费模型。

git clone https://github.com/DDYRich72/UpToCode.git
cd UpToCode
python -m venv .venv

在 Windows PowerShell 上使用 .venv\Scripts\activate，或在 POSIX 上使用 source .venv/bin/activate 激活环境，然后运行：

python -m pip install --upgrade pip
python -m pip install -e ".[test]"
uptocode scan fixtures/bad_python --fail-on critical
uptocode scan fixtures/bad_python --format json --output report.json
uptocode review report.json --approve AA001,AA003 --reject AA012 --non-interactive
uptocode plan report.json --manifest .uptocode/manifest.json --output FIXPLAN.md
python scripts/acceptance.py

首次扫描会有意以 1 退出，因为测试样例包含严重发现项。 其余命令会生成与报告绑定的审查清单和仅包含已批准内容的 FIXPLAN.md；它们不会修改测试样例。若要检查本地 MCP 接口，请从 MCP 客户端运行 uptocode serve --transport stdio --root .，或使用 MCP 注册下的 JSON 注册信息。python scripts/acceptance.py 也会启动真实的 stdio 服务，列出全部十个工具，并离线调用 check_loop。

提交内容的托管传输已部署在 https://uptocode-mcp-1015314816960.us-central1.run.app/mcp。其 bearer 凭据 单独签发，并从 UPTOCODE_API_KEY 读取；切勿提交该凭据，也不要将其输入网站。不可变的生产版本已通过就绪状态、未授权访问、AA001、工具发现、判断门控、速率限制和无载荷日志检查。托管判断已关闭，未配置 OpenAI 密钥，验证过程中没有调用任何付费模型。

扫描、审查、规划

uptocode scan PATH [--format terminal|json|html|github|sarif] [--output FILE]
                         [--judgment --send-code]
                         [--fail-on critical|warning|info]
                         [--include-experimental] [--share-safe]
                         [--baseline FILE|--update-baseline FILE]
                         [--changed-since REF] [--select RULES] [--ignore RULES]
                         [--exclude GLOB] [--severity RULE=LEVEL]
                         [--fail-on-analysis-warning] [--github-summary PATH]
                         [--verbose]
uptocode review REPORT [--approve IDS|--approve-all] [--reject IDS]
                              [--reuse MANIFEST] [--non-interactive]
uptocode plan REPORT --manifest MANIFEST [--output FIXPLAN.md]
uptocode fix REPORT --manifest MANIFEST --runner codex|command
                    [--command TEMPLATE] [--verify-command COMMAND] [--apply]
uptocode serve --transport stdio --root PATH
uptocode serve --transport streamable-http --mode hosted

扫描、审查、规划以及默认的修复预览都不会修改内容：

uptocode scan . --format json --output report.json
uptocode review report.json --approve AA001,AA003 --reject AA012 --non-interactive
uptocode plan report.json --manifest .uptocode/manifest.json --output FIXPLAN.md
uptocode fix report.json --manifest .uptocode/manifest.json --runner codex

review 会将决策绑定到确切的报告指纹。plan 会拒绝不匹配的清单，并且只包含已批准的发现。两个命令都不会编辑已扫描的仓库。 除非提供 --apply，否则 fix 也只是不会写入内容的试运行。应用修复的路径要求 Git 工作区干净；它会为每个已批准的发现创建一个保留的 uptocode/fix-<fingerprint12> 分支/工作树，仅在其中调用选定的外部运行器，验证指纹是否已消失，并且绝不会提交、合并、删除工作成果或更改调用命令的工作区。

退出代码：0 表示未触发任何已配置的阈值；1 表示存在达到或超过 --fail-on 阈值的发现（或触发了请求的分析警告门槛）；2 表示配置无效或扫描发生不可恢复的错误。实验性发现仍会显示，但必须指定 --include-experimental，才会影响 --fail-on。--share-safe 会对 JSON、HTML 或 SARIF 进行脱敏以供分发，同时保留仓库修订版本。Baseline 2.1 会报告新增、持续和已解决的技术债，并在更新时保留 first_seen。抑制项可包含 owner、带引号的 reason 和包含到期日当天的 expires 日期。HTML 必须指定 --output。GitHub 工作流命令会转义不可信的命令数据和属性。SARIF 2.1.0 会省略不存在的字段、声明默认规则级别，并携带稳定的部分指纹。--github-summary PATH 会追加一份有长度限制的 Markdown 摘要；如果设置了 GITHUB_STEP_SUMMARY，摘要也会自动追加到该文件。

Pre-commit

repos:
  - repo: https://github.com/DDYRich72/UpToCode
    rev: v1.1.0
    hooks:
      - id: uptocode

运行 pre-commit install，然后使用 pre-commit run uptocode --all-files。如需将项目徽章复制到自己的 README：

[![Scanned with UpToCode](https://img.shields.io/badge/scanned%20with-UpToCode-175cd3)](https://github.com/DDYRich72/UpToCode)

GitHub Action

仓库附带一个组合式 Action，它会从 Action 检出内容安装 UpToCode、运行扫描、通过 always() 上传 SARIF，然后才返回保留的扫描器退出代码：

permissions:
  contents: read
  security-events: write

steps:
  - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
  - uses: DDYRich72/[email protected]
    with:
      path: .
      fail-on: critical
      version: source
      upload-sarif: "true"

version: source 会从已检出的 Action 源码安装。指定精确的语义化版本（例如 1.0.0）会安装对应的 uptocode PyPI 发行版。如果不需要上传代码扫描结果，请设置 upload-sarif: "false"；否则，调用方工作流需要 security-events: write 权限。

终端输出示例：

UpToCode scan
Coverage: 1/1 files analyzed
Findings: 11 | Warnings: 0 | Redactions: 3
[CRITICAL] AA001 agent.py:21 - Unbounded agent loop
[CRITICAL] AA003 agent.py:11 - Ungated destructive action

隐私模型

• 默认使用静态扫描，不会发起网络请求。
• 除非同时指定 --send-code，否则会拒绝 --judgment。
• 判断请求仅发送规范化证据和经过长度限制、已脱敏的摘录，并按候选规则分组，每条规则仅发送一次。请求使用 gpt-5.6、Pydantic Structured Outputs、store=false、2,000 个 token 的输出上限、30 秒超时，以及最多调用六条规则。
• 在输出报告或判断结果前，会替换可识别的 OpenAI 密钥、AWS 访问密钥、Bearer token、电子邮件地址和美国社会安全号码。检测范围有意设得较窄，不能替代专用的密钥/PII 扫描器。
• 会遵循嵌套的 .gitignore 文件、默认的构建/依赖/生成文件排除规则、.uptocode.yml、每个文件 1 MiB 和总计 4 MiB 的限制、对二进制文件和非 Python 文件的排除规则，以及明确的抑制项。生产环境的 UpToCode 源码要求抑制项数量为零。
• 拒绝、超时、身份验证失败或 API 失败都不会删除静态扫描结果；报告会记录判断状态为 partial 或 failed，并附上分析警告。

离线测试或验收套件不会发起实际 API 调用。提交冒烟测试需要密钥，并且需要单独批准付费使用。

规则

ID	架构缺陷	层级	严重程度	主要指南
AA001	Agent 循环无界	静态	严重	Agents SDK 运行器
AA002	缺少输出／运行预算控制	静态	严重	OpenAI 实用指南
AA003	未设关卡的破坏性操作	静态 + 判断	严重	Agents SDK 审批，OpenAI 安全指南
AA004	工具参数未验证	静态	严重	OpenAI 函数调用，Anthropic 工具定义
AA005	提示词中包含未经处理的不可信内容	判断	严重	OpenAI 安全指南，Anthropic 防护措施
AA006	暴露机密信息或范围较窄的个人身份信息（PII）	静态	严重	OpenAI 安全指南
AA007	缺少超时、重试或重试退避机制	静态	警告	OpenAI 实用指南
AA008	编排复杂度缺乏合理依据	判断	警告	Anthropic 高效 Agent，OpenAI 实用指南
AA009	工具架构不佳	判断	警告	OpenAI 函数调用，Anthropic 工具定义
AA010	副作用执行前未验证模型输出	静态 + 判断	警告	OpenAI 函数调用，OpenAI 安全指南
AA011	Agent 缺少评估覆盖	静态 + 判断	警告	OpenAI 评估，Google ADK 评估
AA012	Agent 缺少可观测性	静态	信息	Agents SDK 跟踪
AA013	上下文增长无界	静态	警告	Anthropic 高效 Agent，OpenAI 实用指南
AA014	网络 MCP 未启用身份验证	静态	严重	MCP 授权，FastMCP 令牌验证
AA015	MCP 工具缺少注释	静态	警告	MCP 工具
AA016	MCP 工具参数未启用严格模式	静态	警告	MCP 工具，Pydantic 配置
AA017	工具错误未作区分	静态 + 判断（实验性）	警告	MCP 工具错误，Claude 工具调用错误
AA018	仅通过提示词执行策略	静态 + 判断（实验性）	警告	NIST AI 600-1，OWASP 过度代理权限
每个静态判定都需要已识别的语法和有源码依据的证据。对于不受支持或动态的结构，会产生覆盖缺口或分析警告；绝不会在未说明的情况下判定为无问题。

VS Code

editor/vscode-uptocode/ 中的独立扩展会在保存时扫描 Python 文档，并将有效的 UpToCode JSON 发现结果转换为文件诊断。它不会运行守护进程或后台仓库扫描，也不提供自动修复。使用以下命令构建并安装本地包：

cd editor/vscode-uptocode
npm ci
npm run verify
code --install-extension uptocode-vscode.vsix

在 VS Code 中配置 uptocode.executable、uptocode.extraArgs 和 uptocode.failOn。是否发布到 Marketplace 仍由操作人员决定。

支持和不支持的结构

可识别的证据包括：

• OpenAI Runner.run/run_sync 限制：省略 max_turns 时判定为无问题，因为 SDK 默认值有上限；显式数值限制判定为无问题；max_turns=None 会被标记。
• 静态可解析的 LangGraph recursion_limit。
• 可检测到退出条件的 while True 循环、常量边界，以及简单的递归基例。
• OpenAI Responses 模型调用、输出上限、客户端/调用超时、客户端重试上限，以及简单的源码级运行预算。
• @function_tool 审批、其模型控制的参数传入常见 SQL/ shell/文件/网络接收点、与参数关联的验证、Agent 评估标记/测试，以及附近的日志记录/追踪证据。
• docs/frameworks/ 中记录的 Anthropic Messages/Agent SDK、CrewAI、PydanticAI 和 LlamaIndex 框架约定。
• 对 .ts、.tsx 和 .mts 进行 Tree-sitter 分析：自定义无限循环、OpenAI Agents JS maxTurns、LangGraph.js recursionLimit、令牌/超时/重试选项、Zod 工具参数和追踪导入。

已知限制：

• TypeScript 覆盖范围有意限制为 AA001、AA002、AA004、AA007 和 AA012；其他所有规则都会按语言报告为不适用。
• 动态导入、元编程、超出受支持的单跳项目调用图的分派，以及仅在运行时发生的行为，仍无法确定；识别到这些情况时会产生覆盖警告。
• 静态副作用和架构分析较为保守，可能产生误报；规划前应审查发现结果。
• 密钥/PII 识别仅覆盖一小组明确模式，不涵盖任意凭据或个人数据。
• 不提供指令文件 lint、运行时追踪服务、进程内源码修改型 codemod、浏览器仓库上传或账户系统。显式的 fix --apply 修复会委托给外部运行器，并在隔离的 Git worktree 中执行。

配置

在扫描根目录创建 .uptocode.yml：

exclude:
  - generated/
  - vendor/
max_file_size: 1048576

报告中的路径会规范化为相对于扫描根目录的路径。报告 2.2 的覆盖记录会汇总并按语言列出已发现/已分析的文件、检测到的框架、已评估/不适用的规则、抑制项、警告、判定状态和脱敏计数。

独立 HTML 报告包含支持键盘操作的“批准/拒绝”决策，并通过 Blob 在本地下载与报告绑定的 ReviewManifest 2.0。报告不会发出网络请求；uptocode plan 仍是唯一的清单使用方，并且绝不会编辑源码。

审查前，请从一次扫描生成匹配的 HTML 和 JSON：

uptocode scan . --format html --output report.html --json-output report.json
# Review report.html and download uptocode-review-manifest.json
uptocode plan report.json --manifest uptocode-review-manifest.json --output FIXPLAN.md

MCP 注册

直接运行 stdio 服务 uptocode serve，或将模块注册到 MCP 客户端：

{
  "mcpServers": {
    "uptocode": {
      "command": "python",
      "args": ["-m", "uptocode.mcp_server"],
      "cwd": "/absolute/path/to/this/repository"
    }
  }
}

本地模式提供仓库／文件／源代码／差异审计、严格模式校验和循环检查、规则目录、审查以及 FIXPLAN 生成。其范围限制在配置的规范工作区根目录内，并包含符号链接防护；且只能加载明确受信任的本地规则包。

托管 Streamable HTTP 模式仅注册已提交内容相关的工具。它不提供仓库或 文件系统路径工具，不会持久化已提交的代码或结果，并要求使用私测 Bearer 密钥，这些密钥以 SHA-256 摘要的形式配置在 UPTOCODE_API_KEY_HASHES 中。经过身份验证的 请求使用基于内存的逐密钥令牌桶（UPTOCODE_RATE_LIMIT_PER_MINUTE，默认值 为 30）；超出限制的请求会返回 429 和 Retry-After。日志仅通过 八个字符的摘要前缀标记流量来源。除非设置 UPTOCODE_HOSTED_JUDGMENT=true，否则会拒绝托管判定；其默认值 为 false。启用全局门控后，仍须遵守 judgment=true, send_code=true 的双重同意 规则。

本地模式会在创建服务时解析一次规范工作区根目录。相对路径和 绝对文件、仓库及差异基准路径都会限制在同一根目录内，并包含符号链接解析。 如果严格模式私有契约发生变化，固定版本的 MCP SDK 兼容性检查会在服务器启动时失败，并显示已安装的 SDK 版本；升级 流程记录在 docs/operations.md 中。

功能主页和连接配置生成器位于 web/ 中。/connect 可生成本地 stdio 或托管 Codex MCP 配置；Bearer 密钥保留在用户的本地环境中，页面绝不会要求用户输入或传输这些密钥。

UpToCode 审计自身

发布门禁会运行 python scripts/compliance.py，检查 UpToCode 的生产 Python 源代码。目前已验证的结果为零项发现、零项抑制，以及零条无法解释的 分析警告。刻意设置的错误样例和合成脱敏哨兵仍作为测试证据保留，但不纳入对生产代码的 结论。此自用验证属于每个 发布候选版本的一部分，同时还包括完整的离线测试套件和分支覆盖率下限。

使用 Codex 和 GPT-5.6 构建

Codex 始终是 UpToCode 的开发协作者：它将产品 规格转化为垂直切片，实现并审查了扫描器、CLI、报告、 MCP 服务、网站和测试，修复了干净克隆中的缺陷，并运行了 Windows/POSIX 提交门禁。UpToCode 还会生成与报告关联的 FIXPLAN.md，其中包含可复制粘贴的 Codex 交接内容，因此分析与编码之间由审批衔接，而非自动修改源代码。 以竞赛为先的工作顺序、决策、进度日志和验证报告均保留在 仓库中，作为此次协作的可审计记录。

GPT-5.6 通过 OpenAI Responses Structured Outputs 提供可选的判定层。 它仅评估需要上下文判定的候选规则所涉及的有限、已脱敏证据。 此功能需用户选择加入两次（--judgment --send-code），使用 store=false，且 当请求失败或遭拒时，绝不会替代或删除确定性的静态发现结果。 常规测试、判定器测试构建和演示试运行完全离线； 任何实时付费调用都需要操作人员单独批准。

项目证据

• 实现规范
• 目标提示词
• 进度与自检分类
• 验证报告
• 架构合规矩阵
• 参考生产规范
• 托管运维与回滚
• 托管评审访问
• 三分钟以内的演示脚本
• 活动规则与证据清单
• 提交证据索引

未经明确批准，本项目工作流不会发布任何仓库、软件包、视频、部署或提交内容。