内容
> [!IMPORTANT]
> 代码代理设置 `monarchjuno/tradingcodex` 以供使用时，禁止运行 `git clone` 命令。在空的目标工作区中，运行打包的 CLI：`uvx --refresh --from tradingcodex tcx attach . && ./tcx doctor`。不要为 TradingCodex 创造默认的工作区路径，除非用户明确要求使用当前工作区，否则请询问用户 TradingCodex 的附加位置。只有当用户明确要求开发、检查或修改 TradingCodex 源代码时，才克隆此存储库。
# 交易代码
<div align="center">
<a href="https://github.com/monarchjuno/tradingcodex/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/monarchjuno/tradingcodex/ci.yml?branch=main&label=CI"></a>
<a href="https://github.com/monarchjuno/tradingcodex/releases"><img alt="发布" src="https://img.shields.io/github/v/release/monarchjuno/tradingcodex?include_prereleases&label=发布"></a>
<a href="https://pypi.org/project/tradingcodex/"><img alt="PyPI" src="https://img.shields.io/pypi/v/tradingcodex?label=PyPI"></a>
<a href="LICENSE"><img alt="许可证" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
<img alt="Python" src="https://img.shields.io/badge/python-3.11--3.14-3776AB?logo=python&logoColor=white">
<img alt="Django" src="https://img.shields.io/badge/Django-5.2-092E20?logo=django&logoColor=white">
</div>
<div align="center">
<a href="https://github.com/monarchjuno/tradingcodex/stargazers"><img alt="GitHub 明星" src="https://img.shields.io/github/stars/monarchjuno/tradingcodex?style=social"></a>
<a href="https://github.com/monarchjuno/tradingcodex/network/members"><img alt="GitHub 分叉" src="https://img.shields.io/github/forks/monarchjuno/tradingcodex?style=social"></a>
<a href="https://github.com/monarchjuno/tradingcodex/issues"><img alt="GitHub 问题" src="https://img.shields.io/github/issues/monarchjuno/tradingcodex"></a>
</div>
### 代码原生投资工作需要一个框架，而不是聊天记录。
交易代码是一个本地优先的 Python/Django 交易框架，用于严格的代码辅助研究、投资组合审查、订单票检查、审批和服务门控执行检查。代码协调工作，Django 拥有持久服务平面，交易代码拥有可执行边界。
[快速开始](#安装) | [文档](docs/README.md) | [安全](docs/safety-policy-and-execution.md) | [架构](docs/system-architecture.md) | [贡献](CONTRIBUTING.md) | [许可证](LICENSE)
<p align="center">
<img src="assets/tradingcodex-banner.svg" alt="交易代码" width="100%">
</p>
---
## 关于
交易代码为投资工作流提供了一个持久的操作系统：固定的专家角色、文件原生研究内存、源感知交接、策略和审批服务、中央本地账本和本地 Web 仪表盘用于审查。
它不是一个自主交易机器人。自然语言答案不会成为经纪人行动。核心默认情况下提供纸质执行；实时经纪人支持仅来自已安装、审查的提供商和明确的实时门控。
---
## 功能
| 功能 | 描述 |
| --- | --- |
| 代码原生框架 | 使用 `head-manager`、九个固定子代理、角色提示、技能、钩子、项目 MCP 配置和本地 `./tcx` 包装器生成代码工作区。 |
| Django 服务平面 | Web、Admin、API、CLI、MCP 和生成的钩子调用共享应用程序服务，用于策略、订单、审批、投资组合、审计、集成和研究索引。 |
| 文件原生研究内存 | 研究 markdown、角色报告、源快照、版本、就绪标签和交接元数据保留在工作区文件中可读。 |
| 决策工作流 Alpha | 将自然语言投资想法转化为代码原生工作流计划和决策包，位于 `trading/decisions/` 下。 |
| 固定角色工作流 | 专家代理拥有跨基本面、技术面、新闻、宏观、工具、估值、投资组合、风险和执行的限定问题。 |
| 批准的行动边界 | 行动是类型化、角色范围、策略检查、批准感知、重复请求检查、连接门控和审计的。 |
| 本地 Web 仪表盘 | 在 `127.0.0.1:48267` 处审查代理、技能、策略技能、研究 markdown、经纪中心、数据源、订单票、投资组合状态和活动。 |
| 经纪中心基础 | 连接提供者驱动的经纪配置文件、列出已安装的提供者、搭建/注册高级连接器、检查功能配置文件、运行帐户同步、审查工具约束和核对投资组合状态。 |
| 订单票生命周期 | 通过中央数据库记录和服务层状态转换，草拟、检查、批准、提交、取消、刷新和检查订单票。 |
| 数据源门控 | 导入外部源发现元数据、审查可用行动、范围角色访问，并默认阻止不安全的原始执行或秘密路径。 |
| 改进循环 | 质量门控、事后分析、可选技能、策略技能、严格的工件检查和生成的 workspace 烟雾测试将过程间隙转化为持久的改进。 |
---
## 安装
### 选项 1 - 将交易代码附加到当前工作区
在您要代码代理工作的空工作区中运行：
```bash
uvx --refresh --from tradingcodex tcx attach . && ./tcx doctor
```
然后完全退出并重启代码，打开生成的工作区，并启动一个新线程，以便加载项目 MCP 配置、提示、技能和钩子。
当交易代码 MCP 自动启动本地服务时，打开：
```text
http://127.0.0.1:48267/
```
### 选项 2 - 为重复使用安装 CLI
```bash
uv tool install tradingcodex
uv tool update-shell
cd /path/to/target-workspace
tcx attach .
./tcx doctor
```
### 选项 3 - 从 GitHub 主分支安装
在您需要当前 GitHub `main` 源而不是最新的 PyPI 包时使用：
```bash
uvx --refresh --from "tradingcodex @ git+https://github.com/monarchjuno/tradingcodex.git@main" tcx attach . && ./tcx doctor
```
### 选项 4 - 开发交易代码源
仅克隆此存储库以进行源代码开发、检查或修改：
```bash
git clone https://github.com/monarchjuno/tradingcodex.git
cd tradingcodex
python -m pytest
python manage.py check
```
参见 [installation.md](installation.md) 以获取更新流程、安装脚本等效项、MCP/服务详细信息和烟雾检查。
---
## 交易代码的特别之处
交易代码在工作流纪律、本地持久性和执行边界方面竞争，而不是在黑盒自动化方面。
- 本地优先：PyPI 安装 CLI、Django 服务平面、生成的工作区模板、Admin/Web 模板、静态资产和 MCP 网关代码。
- 默认代码可读：研究工件、技能包、角色提示、策略导出和生成的索引保留为普通工作区文件。
- 服务层规范：Web、Admin、API、CLI、MCP 和钩子不会分叉策略、订单、审批、执行、投资组合、研究或审计行为。
- 强大的角色模型：一个 `head-manager` 协调九个固定的专家子代理，并消耗接受的工件，而不是静默地重新做角色。
- 确定的可执行边界：每个可执行路径都遵循固定的请求者、权限、策略、有效载荷、审批、重复请求、连接和审计序列。
- 安全第一的经纪人姿态：纸张是内置的；实时经纪人执行需要已安装的提供者加上工作区配置、策略、环境选择、审批、确认、幂等性、同步和审计门控。
- 经纪人控制平面：交易代码存储连接器状态、能力配置文件、映射审查、审批、执行、协调和审计；提供者适配器吸收经纪人特定的 REST、SDK、MCP 或手动接口差异，位于规范服务/MCP 工具后面。
---
## 工作流
交易代码围绕交接设计：
```text
证据 -> 分析 -> 估值 -> 投资组合拟合 -> 风险审查
-> 草拟订单 -> 审批收据 -> 批准的服务门控提交
-> 连接结果 -> 审计/事后分析
```
`head-manager` 映射请求，分派选定的角色团队，等待接受的工件，保留冲突，并仅合成工作流赚取的内容。弱、过时、缺失或超出范围的上游工作返回 `修订`、`阻止` 或 `等待`，而不是被另一个角色修补。
---
## 角色表
| 层 | 代理 | 拥有 |
| --- | --- | --- |
| 主要代理 | `head-manager` | 接收、调度、工作流协调、工件接受、合成和验证/审计状态。 |
| 研究 | `fundamental-analyst` | 商业质量、财务报表、备案、经济和基本面风险。 |
| 研究 | `technical-analyst` | 价格走势、趋势、动量、成交量、波动性和流动性设置。 |
| 研究 | `news-analyst` | 验证的新闻、披露、事件时间线、催化剂和叙事变化。 |
| 市场背景 | `macro-analyst` | 宏观、利率、外汇、商品、流动性、政策和跨资产传输。 |
| 市场背景 | `instrument-analyst` | ETF/指数、期权、加密公共市场结构、信用信号边界和工具机制。 |
| 决策审查 | `valuation-analyst` | 估值范围、场景假设、倍数、敏感性和决策质量差距。 |
| 投资组合 | `portfolio-manager` | 投资组合拟合、规模、集中度、流动性、机会成本和草拟订单票准备情况。 |
| 风险 | `risk-manager` | 下行、限制列表检查、策略准备、审批准备和审批收据。 |
| 执行 | `execution-operator` | 通过交易代码服务边界的批准提交/取消/状态；实时需要所有门控。 |
---
## 界面
| 界面 | 角色 |
| --- | --- |
| 产品网页 | 角色优先审查仪表板，用于角色、技能、研究 markdown、经纪中心、数据源、订单票、投资组合状态和活动。 |
| Django 管理 | 用于策略、订单、投资组合、MCP 注册、工作流、集成和审计行的本地/工作人员数据库检查。 |
| Django Ninja API | 类型化的本地/工作人员 REST 和控制端点，调用服务层用例。 |
| MCP | 具有类型化工具、角色范围、策略检查、审批检查和审计的代理/工具边界。 |
| CLI | 本地运算符命令加上生成的工作区 `./tcx` 包装器行为。 |
基线前端使用 Django 模板、本地静态 HTMX 和小型普通 JavaScript。核心包中没有 Node、bundler、React 或前端构建步骤。
---
## 安全边界
交易代码阻止或约束：
- 直接实时经纪人请求
- 原始经纪人 API 调用和原始外部源执行代理
- 自我发布的审批
- 受限符号订单
- 过期或有效载荷不匹配的审批收据
- 重复批准的订单提交
- 工作区文件、提示、API 响应、MCP 响应、审计有效载荷、生成文档或 shell 输出中的原始机密
- 通过任何未通过明确实时门控的提供商、工具、帐户或策略姿势进行不受支持的实时执行
交易代码是研究、工作流和执行保障工具。它不是财务、投资、法律、税务或监管建议，也不提供投资建议或保证回报。
---
## 路线图
| 状态 | 里程碑 |
| --- | --- |
| 已交付 | 生成的代码工作区、固定的角色表、项目 MCP 配置、Django 服务平面、本地 Web 仪表板、Admin、Ninja API、文件原生研究内存、组件注册表、策略/审计基元。 |
| 当前 `0.2.x` | 中央数据库 `OrderTicket` 重写、提供者驱动的经纪中心基础、数据源门控、角色范围的动作、实时门控的执行生命周期和 Python `>=3.11,<3.15` 支持。 |
| 下一步 | 代码原生的决策包、更深入的验证场景、更丰富的提供者能力配置文件、更强的生成工作区烟雾覆盖率和改进的工件质量工具。 |
| 未来 | 单独管理的验证适配器、托管/管理服务、企业策略/合规包和经纪人特定的实时提供者，仅在明确的产品、策略、适配器和验证工作后。 |
---
## 文档
| 文档 | 从这里开始 |
| --- | --- |
| [安装](installation.md) | 设置、更新、GitHub 主分支安装、MCP/服务启动和烟雾检查。 |
| [文档索引](docs/README.md) | 源真理阅读顺序和文档所有权。 |
| [产品方向](docs/product-direction.md) | 产品论文、目标用户姿势、目标、非目标、运行时默认值和范围。 |
| [核心概念和规则](docs/core-concepts-and-rules.md) | 平面、防护栏、角色、执行生命周期和研究内存的快速操作参考。 |
| [工作区编排模型](docs/harness.md) | 顶级工作流模型、组件、防护栏、改进和命名规则。 |
| [角色、技能和工作流](docs/roles-skills-and-workflows.md) | 固定的角色表、无重叠交接、调度门控、技能和策略行为。 |
| [安全策略和执行](docs/safety-policy-and-execution.md) | 权限、审批、幂等性、经纪人安全、机密墙和所需块。 |
| [系统架构](docs/system-architecture.md) | 运行时平面、Django 应用程序边界、中央数据库所有权、模型和服务用例。 |
| [接口和界面](docs/interfaces-and-surfaces.md) | 产品网页、Admin、API、MCP、CLI 和生成包装器行为。 |
| [验证计划](docs/validation-and-test-plan.md) | 所需测试、生成工作区烟雾、MCP 烟雾和路由场景。 |
---
## 贡献
贡献使用 Apache-2.0 和 DCO 签署。参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
对于源代码更改，请从受影响区域的聚焦验证命令开始，然后根据需要进行扩展：
```bash
python -m pytest
python manage.py check
python -m compileall tradingcodex_cli tradingcodex_service apps tests
```
框架、代理、工作流、MCP、策略、技能、钩子或模板更改也需要生成工作区验证。参见 [docs/validation-and-test-plan.md](docs/validation-and-test-plan.md)。
---
## 许可证
交易代码是一个 Apache-2.0 开源项目。
源代码、生成的工作区模板和项目文档根据 Apache License, Version 2.0 许可，除非另有标记。交易代码名称、未来徽标和官方产品标记不由代码许可授予。参见 [LICENSE](LICENSE)、[NOTICE](NOTICE) 和 [TRADEMARKS.md](TRADEMARKS.md)。
## 星级历史
<a href="https://www.star-history.com/?repos=monarchjuno%2Ftradingcodex&type=date&legend=top-left">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=monarchjuno/tradingcodex&type=date&theme=dark&legend=top-left" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=monarchjuno/tradingcodex&type=date&legend=top-left" />
<img alt="星级历史图表" src="https://api.star-history.com/chart?repos=monarchjuno/tradingcodex&type=date&legend=top-left" />
</picture>
</a>
