Artha Council

Artha Council

Artha 是一个 AI 辅助的股票研究与投资组合自动化系统。它从庞大的美国股票池中筛选候选股票、评估投资机会排名、邀请独立分析师角色辩论最有潜力的候选标的、监控活跃的投资论点，并在订单执行前通过确定性的经纪商门控。

1.4 版通过为可移植的本地访问或受 OAuth 保护的远程访问提供源代码／构建来源信息，强化了 MCP 服务。它支持现有的美国市场工作流以及适配市场规则的印度现金股票经纪商适配器，同时不会将美国研究数据视为印度数据。 印度适配器提供经纪商验证的工具查询，以及默认拒绝的整股交割限价执行，并要求配置当前的静态 IP。

由 Sarath（@akira231097）创建并维护。

请参阅设计说明和架构图，直观了解研究、Council、执行和审计的边界。

Artha 是研究软件，不构成财务建议。公开默认设置无法执行实盘交易。任何启用经纪商集成功能的人，都有责任检查源代码、自身配置、经纪商条款和适用要求。

Artha 的存在意义

大多数股票筛选工具在完成股票代码排名后就止步了。Artha 将投资视为一个有状态的操作系统：

1. 从庞大的股票池中寻找候选标的。
2. 验证数据质量和执行可行性。
3. 将稀缺的 Council 关注力用于最有潜力的候选标的。
4. 将投资判断与订单执行分开。
5. 监控每个持仓的投资论点，并将重大变化提交给卖出 Council 审议。
6. 根据经纪商状态核对预期操作。
7. 保留审计所需的证据和状态变更记录。

系统流程

Market data providers
  -> universe and promotion funnel
  -> investment sanity checks
  -> broker-aware candidate router
  -> opportunity scout
  -> fundamental / technical / risk analysts
  -> CIO synthesis
  -> execution officer
  -> deterministic broker review and placement gates
  -> reconciliation, thesis tracking, Telegram, supervisor

卖出流程独立于新买入容量运行：

Portfolio snapshot
  -> position and thesis monitor
  -> deterministic stop / invalidation triggers
  -> sell Council for judgment decisions
  -> execution officer
  -> broker review and exact-order placement gate
  -> post-fill reconciliation

重要设计规则

研究不等于执行

Council 回答：“这项投资是否具有吸引力？”

执行层回答：“现在能否安全地执行这一笔确切的订单？”

即使一家公司表现良好，也可能暂时无法买入，因为报价已过期、价差过大、价格高于获批上限，或经纪商审核尚未完成。这些情况不会改变投资论点。

缺少经纪商凭证时禁止下单

涉及资金的操作路径均采用默认拒绝策略。模型声称检查已通过还不够；Artha 要求提供决定性的结构化经纪商输出。

暂停买入时仍继续监控投资组合

持仓数量限制和已投资额度限制只会暂停新买入。监控、卖出审核、对账、健康检查和提醒仍会继续运行。

主要组件

• artha/funnel.py - 广泛标的池的晋级和多策略袖珍组合排名。
• artha/broker_router.py - 报价、流动性、可交易性和数据可行性。
• artha/opportunity_scout.py - Council 之前基于 Agent 的证据审查和排名。
• artha/council.py - 分析师角色、评分审计和 CIO 综合研判。
• artha/execution_officer.py - Stage A 和 Stage B 执行推理。
• artha/alpha_shadow.py - 非权威 Alpha 实验和结果跟踪。
• artha/broker_capacity.py - 投资组合和每日买入容量计算。
• artha/stand_down.py - 仅暂停买入及下一交易日重置行为。
• artha/sell_engine.py - 持仓触发条件和卖出端编排。
• artha/sell_council.py - 持有、减仓和退出审查。
• artha/position_classification.py - 券商持仓的行业和子行业修复。
• artha/execution_learning.py - 交易后执行质量测量。
• artha/fill_finalizer.py - 券商成交记账和幂等状态最终确认。
• artha/robinhood_bridge.py - 券商交接、审查、放行和对账。
• artha/scheduler.py - 定时扫描和生命周期编排。
• artha/supervisor.py - 生产环境健康状况和就绪情况检查。
• artha_mcp/ - MCP 工具、资源、提示词、授权、任务、 脱敏、研究适配器、精确订单回执和券商对账。
• dashboard/ - 本地操作员仪表板。

完整的组件图请参阅 架构。

快速开始

要求：Python 3.12 或更高版本，以及 Node.js 20 或更高版本。

git clone https://github.com/akira231097/artha-council.git
cd artha-council
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e .
npm ci
cp .env.example .env

在 .env 中添加你自己的服务提供商凭据。评估系统期间，请将所有 Robinhood 设置保持在安全默认值。

python run.py overview
python run.py analyze AAPL MSFT V
python run.py broker-router-preview --assume-market-open --no-persist
python run.py supervise
artha-mcp --check

MCP

通过本地 stdio 使用 .mcp.json.example 连接任意兼容 MCP 的主机，或在 OAuth 和 TLS 保护下部署无状态 Streamable HTTP。服务器启动时为只读模式，且杀开关处于启用状态。

artha-mcp

用户需自行提供模型订阅、数据订阅、券商凭据和通知凭据。MCP 服务不会提供或共享维护者的账户。有关确切的功能和安全边界，请参阅 Artha MCP 和 印度支持。有关发布指纹、滚动与稳定通道，以及本地来源故障关闭晋级路径，请参阅 MCP 更新。

验证

python -m compileall -q artha artha_mcp dashboard run.py
python -m unittest discover -s tests -t . -v
python scripts/check_release_integrity.py
python -m artha.test_enhancements
python -m artha.test_alpha_pipeline_hardening
python -m artha.test_production_hardening
python -m artha.test_feedback_loop_hardening

测试使用合成固件，不得要求真实的券商凭据。

Docker

随附镜像支持核心 Python 研究 CLI：

docker build -t artha-council .
docker run --rm --env-file .env artha-council overview

券商快照辅助工具有意排除在这个精简版 Python 镜像之外；它需要单独配置的 Node.js MCP 运行时和券商访问权限。

Dockerfile.mcp 会构建非 root MCP 镜像。每次经过测试的默认分支更新后，都会刷新 main 镜像标签；发布版本保持不可变。

公开发布边界

此代码库包含源代码、测试、文档和安全配置模板。它有意排除：

• API 密钥、OAuth 令牌和 .env 文件
• 券商账户标识符和快照
• 投资组合、订单历史和交易记录
• SQLite 日志和运行时状态
• 生成的档案、跟踪记录、报告和日志
• Telegram 令牌、聊天标识符和回调令牌
• 本地 OpenClaw、launchd 和工作站配置
• 第三方市场数据负载

第三方数据和服务仍受各自的许可和条款约束。Apache 许可证适用于 Artha 源代码，不适用于服务提供商数据或券商访问权限。

项目文档

• 架构
• 设计说明和图表
• 公开发布和数据边界
• Artha MCP
• MCP 源对齐和更新
• 印度支持
• 安全政策
• 贡献指南
• 作者
• 变更日志
• Apache License 2.0

许可证和引用

Artha Council 根据 Apache License 2.0 授权。分发副本和修改版本时，必须保留 NOTICE 中所述的适用许可证、版权和署名声明。

引用本项目时，请使用 CITATION.cff。GitHub 通过仓库中的 引用此仓库 控件提供该文件。