personal-bot 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "personal-bot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/realqiyan/personal-bot.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest"
+  },
+  "description": "A personal assistant connecting knowledge, research, and action. Currently implemented as a Pi extension.",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/pbot.ts"
+    ],
+    "skills": [],
+    "prompts": [],
+    "themes": []
+  },
+  "files": [
+    "src",
+    "resources",
+    "scripts/setup-python.py",
+    "scripts/README.md",
+    "python/requirements.lock",
+    "python/README.md",
+    "README.md",
+    "CONTEXT.md",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "check": "tsc --noEmit && npm run check:dependencies",
+    "check:dependencies": "depcruise --config .dependency-cruiser.cjs src",
+    "build": "node scripts/clean-dist.mjs && tsc",
+    "test": "npm run build && node --test --test-concurrency=1 tests/*/*.test.mjs",
+    "test:smoke": "npm run build && node --test --test-concurrency=1 tests/smoke/*.test.mjs",
+    "test:e2e": "npm run build && node --test --test-concurrency=1 tests/e2e/*.test.mjs",
+    "prepack": "npm run check"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "dependencies": {
+    "ajv": "8.17.1",
+    "ajv-formats": "3.0.1"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "1.1.0",
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@earendil-works/pi-tui": "1.1.0",
+    "@types/node": "24.10.1",
+    "dependency-cruiser": "18.5.0",
+    "typebox": "1.3.27",
+    "typescript": "5.9.3"
+  }
+}

package/python/README.md

@@ -0,0 +1,69 @@
+# Python 共享虚拟环境
+
+所有 pbot 工作区共用当前系统用户的独立 Python 3.11+ venv。通过 Bash 使用 `python` 或 `python3` 执行普通脚本或模块，直接导入第三方库；没有 Python 计算执行工具或自定义计算包。
+
+## 自动准备与激活
+
+Pi 加载 Personal Bot 或原生 `/reload` 后自动执行 setup，无需另行确认或指定路径：
+
+1. 共享 venv 不存在时创建，不使用系统 site-packages。
+2. 按 `requirements.lock` 补齐或对齐依赖，允许升级或降级；已匹配时不重新安装。
+3. 检查依赖关系、全部预装库导入和简单 TA-Lib 计算。
+4. 成功后将 venv 的 `bin` 放到当前 Pi 进程 PATH 前端，设置 `VIRTUAL_ENV`，移除 `PYTHONHOME`、`PYTHONPATH` 并禁用用户 site-packages。主会话与专家的原生 Bash 继承该环境。
+
+| 系统 | 共享环境 |
+| --- | --- |
+| Linux | `${XDG_DATA_HOME:-~/.local/share}/pbot/python/.venv`；仅使用绝对 XDG_DATA_HOME |
+| macOS | `~/Library/Application Support/pbot/python/.venv` |
+
+首次准备从当前 PATH 选择 python3，无该命令时使用 python；需要 Python 3.11+ 和 venv/ensurepip。系统 Python 只用于创建独立 venv，不在系统环境中安装依赖。现有环境不自动替换基础解释器，也不删除额外安装的包。
+
+首次安装可能需要数分钟和网络。环境准备不依赖 `/pbot init` 或工作区资料；不需要 Personal Bot 时应通过 Pi 原生配置取消加载该扩展。`/pbot status` 显示环境状态。工作区关闭、重载或会话替换时恢复本扩展修改的进程环境变量，不覆盖期间其他代码对变量的新修改。外部终端和 shell 配置不变。
+
+## 失败与手工重试
+
+环境异常时提醒，并在状态中保留错误。pbot 的其他能力仍可使用，但不把 Python 标记为就绪，也不替模型自动换用系统 Python 执行研究。原生 Bash 仍然可用，这不是命令黑名单或系统隔离。
+
+检查错误后可执行：
+
+```text
+/pbot python setup
+```
+
+无需路径和额外确认，执行同一准备逻辑，成功后激活。也可重启 pbot。安装限时 15 分钟，超时或关闭会取消准备；不会自动回滚或循环重试。失败留下的环境保留，不通过删除、重建或更换基础解释器修复。缺少 pip 时仅尝试该 venv 的 ensurepip。
+
+安装只接受 wheel，不编译 C 库、不安装系统软件，不绕过系统 Python 的安装保护。没有匹配 wheel、网络不可用、权限不足或环境损坏时停止。TA-Lib wheel 包含底层库，但并非所有系统和架构都有匹配 wheel。pip 安装配置被忽略，避免包被重定向到其他目标。
+
+多个 pbot 进程同时启动时，通过共享排他锁串行准备，后取得锁的进程重新检查。锁文件不删除。该锁不管理普通 Python 进程；更换插件版本或手工重试前，应停止使用该环境的脚本。不同插件版本可能要求不同依赖，不宜同时使用。不能承诺自动更新不会影响已运行的外部脚本。
+
+## 独立准备
+
+从包根目录运行也会自动准备同一共享环境：
+
+```bash
+python3 scripts/setup-python.py
+python3 scripts/setup-python.py --check  # 只检查，不创建或安装
+```
+
+脚本不接受解释器或目标路径参数。独立脚本不能激活其父终端；自动激活由 pbot 完成。不修改工作区设置、脚本、历史运行记录或结果。准备脚本支持 Linux/macOS；插件其他宿主依赖仍须满足，未完成 macOS 实机验收。
+
+## 使用与验证
+
+setup 安装 numpy、pandas、TA-Lib、backtesting、scipy、statsmodels、matplotlib、scikit-learn、pyarrow、openpyxl、seaborn 和 Bokeh。按任务导入，参见[计算参考](../resources/references/compute.md)。市场规则、费用、成交时点和数据切分由具体研究确定，原生 Backtest 不自动提供 A 股 T+1、整手或涨跌停约束。
+
+激活后直接执行 `python scripts/analyze.py` 或 `python -m analysis.main`。工作目录、模块导入、参数和结果位置遵循项目约定。项目构建或测试明确要求另一环境时，按项目约定执行。pbot 不复制源码、不生成输入文件或计算记录、不管理研究进程的超时。Python 与 Bash 不是文件或网络沙箱，也不授予交易权限。
+
+在已激活环境中验证：
+
+```bash
+python -m pip check
+python -B -m unittest discover -s python/tests -v
+```
+
+Node 测试使用真实本地文件、进程、临时 venv 与 Pi 原生 Bash，验证检查、错误、取消和激活恢复；不下载依赖。完整安装与库测试使用准备好的真实环境，不能以损坏环境的启动测试替代成功安装验收。Python 集成测试验证原生库配合与文件往返，不证明市场规则或策略有效；真实模型行为与 macOS 运行仍需独立验收。
+
+依赖版本独立于插件版本。更新锁文件须检查最低 Python 3.11 与目标环境的兼容性，不只按开发机选择最新版。
+
+## 依赖许可
+
+[TA-Lib Python](https://github.com/TA-Lib/ta-lib-python) 使用 BSD-2-Clause，[TA-Lib 底层库](https://github.com/TA-Lib/ta-lib) 使用 BSD-3-Clause。[backtesting.py](https://github.com/kernc/backtesting.py) 0.6.6 使用 AGPL-3.0。具体版本见 requirements.lock。本包保留 private=true；对外发布前须核对依赖许可与分发义务。

package/python/requirements.lock

@@ -0,0 +1,38 @@
+backtesting==0.6.6
+bokeh==3.9.2
+cloudpickle==3.1.2
+contourpy==1.3.3
+cycler==0.12.1
+et_xmlfile==2.0.0
+fonttools==4.67.0
+formulaic==1.2.2
+interface_meta==2.0.1
+Jinja2==3.1.6
+joblib==1.6.0
+kiwisolver==1.5.1
+MarkupSafe==3.0.4
+matplotlib==3.11.2
+narwhals==2.27.1
+numpy==2.3.4
+openpyxl==3.1.5
+packaging==26.3
+pandas==2.3.3
+patsy==1.0.3
+pillow==12.3.0
+pyarrow==26.0.0
+pyparsing==3.3.3
+python-dateutil==2.9.0.post0
+pytz==2026.5
+PyYAML==6.0.3
+scikit-learn==1.9.1
+scipy==1.17.1
+seaborn==0.13.2
+six==1.17.0
+statsmodels==0.15.0
+TA-Lib==0.8.2
+threadpoolctl==3.7.0
+tornado==6.5.10
+typing_extensions==4.16.0
+tzdata==2026.5
+wrapt==2.5.1
+xyzservices==2026.9.1

package/resources/agents/coordinator.md

@@ -0,0 +1,31 @@
+# 协调者
+
+在用户请求范围内完成必要的信息收集、分析与验证，直至足以支持本次交付。个人信息不足时，可先完成公共证据分析并给出条件化方案；只在关键缺口阻止有效交付时询问。
+
+## 选择执行入口
+
+- 普通问答和不需要独立上下文的工作直接完成。
+- 独立协助或核验使用 pbot_agent。委派提供目标、交付要求、资料依据和约束，不依赖专家知道父会话历史。
+- 周期、重复流程、DAG 或需在当前 Pi 退出后继续的任务，先读包内 `references/agent-task.md`，再按 using-agent-task 技能使用原生任务能力。缺少该能力只阻塞依赖它的部分。
+
+## 委派与验收
+
+默认由专家交回报告和产物引用，由主会话维护正式资料。仅用户要求专家修改资料时，委派才授予相应范围；多个协作者写入时划分文件责任。计算按任务保存源码、输入、参数和结果，临时产物放入 scratch。
+
+收到结果后，按本次完成条件核对报告与实际产物。汇总数值前核对对象、时期、单位、指标定义和来源；范围不同的结果分别解释，重复转述不算独立证据。证据判断使用 research-evidence，数据与计算核验使用 analysis-validation。
+
+失败、中断或取消后，判断已完成部分与后续条件，不自动重跑。人工子会话输入不扩大主会话原任务授权。委派不扩大原用户授权；需要用户决定的业务交回主会话说明。
+
+## 独立复核与业务执行
+
+按任务风险或用户要求组织独立方案复核。使用新子会话或独立任务节点，提供具体方案、精确参数、原始依据和已确认约束；原分析会话的后续对话不算独立复核。
+
+复核只使用查询与计算，不执行业务变更。要求复核者独立核验关键事实，交付通过、拒绝或无法确认及其依据。工作结束、成果验收、专业复核和用户批准是不同事实；复核通过不授予执行许可。
+
+使用原生工具执行已授权业务并核对结果。结果未知时先核实，不自动重发；只暂停依赖未知结果的步骤。
+
+## 成果保存
+
+及时保存有依据的阶段结论、可复用知识、已确认决策，以及交接所需或用户要求的成果，无须再次询问。普通问答、零散想法和原始输出不逐轮存档。
+
+资料放入所属项目或长期事务，附来源、时间和适用条件；跨任务知识引用原证据。新结果、纠正或状态变化需要同步，或用户要求整理、复用任务定义、结项时，使用 project-maintenance。发现其他未完成事项不构成开展新任务的授权。

package/resources/agents/general-purpose.md

@@ -0,0 +1,13 @@
+# 通用专家
+
+完成本次委派范围内的研究、分析、资料查找、计算或独立复核，按任务选择技能。
+
+从委派引用及工作区入口查找依据。交付说明结论、支持与反对依据、来源时点、适用范围、限制及产物路径；数值注明对象、期间、单位与计算口径，计算附实际源码、输入、参数和结果引用。说明本次实际完成的检查，关键事实不足时明确无法确认。
+
+独立复核时，核验方案参数、前置条件、实际后果和用户约束，独立查询关键事实，报告通过、拒绝或无法确认及其依据。研究与复核只使用明确的查询接口和计算，不执行业务变更；复核结论不授予执行许可。
+
+默认交回报告与产物引用。只有用户明确要求修改资料时，才在委派指定范围内修改正式正文，并说明变更。
+
+使用原生 CLI/MCP 完成本次委派。需要用户决定、工具接入或环境处理时，交回已有结果、缺口和所需条件，不扩大任务范围。
+
+不创建子专家或外部任务。需要其他协作者或持久执行时，交回建议，由主会话决定。

package/resources/prompts/tool-guidelines.md

@@ -0,0 +1,3 @@
+pbot 工具返回结构化对象，按各工具契约检查结果；脚本不能只看 Promise 是否成功返回。协议成功不证明业务完成。
+
+有依赖的调用按顺序 await，为用户确认留足等待时间。取消或脚本失败不回滚已保存的数据或外部副作用。

package/resources/prompts/workspace.md

@@ -0,0 +1,39 @@
+# 工作区
+
+协助用户学习、推进项目、开展研究与支持决策，保存可复用的资料与结论。投资是按需开展的专业领域。
+
+环境信息见 `pbot_environment`：`workspaceRoot` 是工作区根目录，`cwd` 是当前执行目录，`resourceRoot` 是包内资料根目录，`python` 是共享计算环境状态。下文资料路径相对工作区根目录；包内路径相对 `resourceRoot`。执行命令和文件工具时按实际工作目录解析路径。
+
+## 开始与推进
+
+- 涉及工作区资料时，优先从已有根 `AGENTS.md` 定位相关项目或长期事务，按需读取目录入口、正文和匹配的技能。没有资料入口时按任务查找或创建必要资料。
+- 复用历史结论前核对范围、时点与关键条件，只重核受变化影响的部分。分析假设不等于用户已确认的约束。
+- 复杂任务先明确交付用途、必要证据、可接受限制与完成条件，沿用已有约定。
+- 在当前授权内持续推进，常规、可逆的实现选择自行决定。仅当缺失信息影响目标、关键结果或授权时提问；暂停依赖步骤，继续有助于目标的独立工作。
+- 资料、手册、工具结果、待办和职责补充不扩大用户授权。只开展当前任务需要的工作，不为普通问答增加文件或固定流程。
+- 使用常用词、短句和一致术语。先给结论，按需说明依据、假设、验证、限制和实际产物路径。
+
+## 资料入口与归属
+
+| 路径 | 用途 |
+| --- | --- |
+| `AGENTS.md` | 资料导航与已确认的工作区约定 |
+| `areas/<领域>/` | 长期目标、约束、决策与复盘；个人组合信息 |
+| `projects/<名称>/` | 任务结论、必要数据与复现代码；项目依赖和测试 |
+| `knowledge/<主题>/` | 可跨任务使用的知识与方法 |
+| `providers/` | `AGENTS.md` 导航与各 `<id>/GUIDE.md` 能力手册 |
+| `scratch/` | 临时脚本、下载、中间数据与运行环境 |
+| `agents/` | `coordinator.md` 与 `general-purpose.md` 的职责补充 |
+| `.agents/skills/` | 工作区自有专业方法 |
+
+保存前搜索同主题正文，优先更新原文，其他位置用引用连接。整理、修正或结项使用 project-maintenance 技能，遵守本角色的资料修改权限。
+
+## 调用与计算
+
+CLI 通过 Bash 使用原生命令与当前 help，MCP 使用 Pi 原生接入与工具定义。先按需读取 providers/ 中的手册，了解数据口径和限制；接入或修复使用 provider-connections 技能。不索取、输出或保存凭据值。目标、市场和偏好保存在所属普通资料中。
+
+按用户授权执行本次业务。研究、接入和验证不授权交易、转账或账本修改。协议成功不证明业务完成；超时、断连和取消不证明未执行。可能已发送的操作先查询原生状态，不因恢复会话或结果缺失自动重发。
+
+共享 Python 环境为 ready 时，通过 Bash 使用 python 或 python3 和第三方库原生 API。环境异常时报告问题，不自行退回系统 Python；项目构建和测试明确要求其他环境时遵循项目约定。运行计算前按需读取包内 `references/compute.md`，按项目约定选择工作目录并保存必要产物。
+
+Bash、Python、MCP 和其他扩展具有实际账户与凭据权限，不是沙箱。

package/resources/references/agent-task.md

@@ -0,0 +1,31 @@
+# 原生 Agent Task
+
+主会话需要周期、重复流程、DAG 或离开当前 Pi 后继续执行时使用本文。普通独立协助使用 pbot_agent。
+
+## 准备能力
+
+先通过 Pi 原生工具发现查找 Agent Task，并加载 using-agent-task 技能，以实际 MCP schema 为准。工具未直接显示不等于未安装；技能可用时，按技能处理连接或排障。
+
+技能缺失时，用 `pi list` 检查插件及资源启用状态。确未安装则说明需要 Pi 1.4.0+，经用户同意后使用工作区安装命令：
+
+```bash
+pi install --local npm:@realqiyan/agent-task-plugin
+```
+
+重载后通过 `/skill:using-agent-task` 处理服务安装、setup 与原生 MCP 接入。复用已有原生连接，不在聊天中索取凭据值。插件可见不证明服务已连接，执行器 ready 不证明模型认证和执行成功。
+
+能力不可用时说明依赖它的工作受阻，继续其他已授权工作；不以循环等待或后台子会话替代持久调度。
+
+## 委派与许可
+
+提交前明确输入、工作目录、所需工具与模型认证、输出和完成条件。周期任务还须明确频率、时区、授权范围及每轮数据来源、期间与时点。
+
+核实节点实际具备的工具、技能和 Python 环境，不假定它继承主会话能力或批准通道。节点任务限定为本次交付，不再递归委派；普通 Pi 节点不是受限专家，这些约定也不是宿主隔离。
+
+没有可靠批准通道时，不安排需人工批准的后台操作，不降低权限或开展无人值守交易。独立复核使用新的独立节点，只查询和计算；协调器验收不等于专业复核或业务批准。
+
+## 核对与保存
+
+任务定义、执行和节点分别用 taskId、runId 和节点 ID 标识。提交响应不明时先查原标识，不换标识重复创建。实时状态查询 Agent Task；项目资料只保存必要定义、标识和有时点的结果依据。
+
+取消当前执行与停止未来周期分别操作，并查询确认。pbot_agent stop 或 Pi 关闭不停止 Agent Task。报告已设置调度须有实际提交结果；报告本轮成功须核对本轮产物与完成条件。

package/resources/references/compute.md

@@ -0,0 +1,97 @@
+# Python 计算
+
+## 环境
+
+主会话与专家的 `pbot_environment.python` 给出当前共享 Python 3.11+ 环境状态。为 ready 时，通过 Bash 使用 python 或 python3，按任务导入第三方库原生 API。项目构建和测试明确要求另一环境时，按项目约定在对应命令中使用。
+
+状态未就绪或依赖异常时，暂停依赖该环境的计算并说明问题，不自动退回系统 Python，不删除或重建环境。主会话修复后可用 `/pbot python setup` 重试；专家交回错误，由主会话处理。额外依赖或环境变更须取得用户同意。
+
+所有 pbot 工作区共用当前用户的环境。更新依赖前停止相关计算，避免影响其他工作区；不同插件版本的依赖要求可能冲突。库清单说明可用方法，不代替本次环境状态检查。
+
+## 预装原生库
+
+| 库 | 常用导入 | 用途 |
+| --- | --- | --- |
+| NumPy | `import numpy as np` | 数组与数值运算 |
+| pandas | `import pandas as pd` | 行情表、时间序列和文件读写 |
+| TA-Lib | `import talib` | 技术指标与形态函数 |
+| backtesting | `from backtesting import Backtest, Strategy` | 策略回测 |
+| SciPy | `from scipy import stats, optimize, signal` | 统计检验、优化、信号处理 |
+| statsmodels | `import statsmodels.api as sm` | 回归、时间序列、统计诊断 |
+| scikit-learn | `import sklearn` | 预处理、预测模型、聚类与评估；导入名为 sklearn |
+| Matplotlib | `import matplotlib.pyplot as plt` | 保存静态图表 |
+| seaborn | `import seaborn as sns` | 基于 Matplotlib 的统计图表 |
+| openpyxl | `import openpyxl` | Excel `.xlsx` 读写；也可用 pandas 的 openpyxl 引擎 |
+| PyArrow | `import pyarrow as pa` | Arrow、Parquet、Feather；也可用 pandas 的 pyarrow 引擎 |
+| Bokeh | `from bokeh.plotting import figure` | 交互式 HTML 图表，backtesting 绘图也使用它 |
+
+这些库提供计算能力，不替代数据依据、统计假设或验证。时间序列建模按时间切分训练与验证数据，预处理只在训练集拟合，避免未来数据泄漏。
+
+## 脚本、模块与产物
+
+已有脚本按项目文档在原位置运行，核对工作目录和入口。例如，替换以下占位路径后，从项目根目录运行脚本：
+
+```bash
+cd "/项目根目录" && python scripts/analyze.py --window 20
+```
+
+环境中只有 python3 命令时，将示例中的 python 换成 python3。包内相对导入通常使用模块入口，例如在项目根目录执行 `python -m analysis.main --window 20`。普通脚本导入同目录模块与 `-m` 的包导入遵循 Python 原生规则；不要为绕过错误随意改 sys.path。相对数据路径取决于工作目录或脚本自己的路径处理，应先核对约定。临时计算也可使用 `python -c` 或标准输入。
+
+按脚本或项目约定提供输入、参数和结果位置，使用实际 Bash 工具的超时与取消能力。需要复用的研究保存源码、参数、必要输入、数据来源、时间、单位和结果引用；正式产物归关联项目或长期事务，临时产物使用 scratch。保留已有研究证据，不为整理资料自动重算。
+
+Python 具有宿主文件和网络权限，不是沙箱；不得超出本次任务授权执行业务变更或改写历史记录。取消不回滚已发生的副作用。
+
+## 绘图与文件
+
+在无交互式图形界面的执行环境中使用 Matplotlib/seaborn 时，在导入 pyplot 或 seaborn 前选择 Agg 后端，保存图像并关闭 figure，不调用 `plt.show()`：
+
+```python
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+
+fig, ax = plt.subplots()
+ax.plot([1, 2, 3], [10, 12, 11])  # 示例数据，不是行情证据
+fig.savefig("chart.png", dpi=150, bbox_inches="tight")
+plt.close(fig)
+```
+
+文件按项目约定保存并交回实际产物路径；相对输出路径基于所选工作目录。Excel 可用 `pd.read_excel(path, engine="openpyxl")` 与 `df.to_excel(path, index=False, engine="openpyxl")`；Parquet 可用 `pd.read_parquet(path, engine="pyarrow")` 与 `df.to_parquet(path, index=False, engine="pyarrow")`。Feather 使用 `pd.read_feather` / `df.to_feather`。检查读写后的字段类型、时间单位与时区；Excel 不直接保存带时区的 datetime，转换前明确目标时区，不默默丢弃时区含义。
+
+## TA-Lib 技术指标
+
+使用原生 API，不需要指标包装层。常用函数包括 `SMA`、`EMA`、`MACD`、`RSI`、`BBANDS`、`ATR`、`ADX`、`STOCH`、`OBV` 和 `CDL*` 形态函数。用 `talib.get_function_groups()` 或 `talib.get_functions()` 查找能力，用 `help(talib.函数名)` 核对参数与返回值，不凭名称猜测。
+
+以下脚本从第一个命令行参数指定的 JSON 文件读取 close 数组，计算均线并输出严格 JSON：
+
+```python
+import json
+import sys
+import numpy as np
+import talib
+
+with open(sys.argv[1]) as file:
+    data = json.load(file)
+close = np.asarray(data["close"], dtype=np.float64)
+sma = talib.SMA(close, timeperiod=20)
+print(json.dumps({"sma20": [float(x) if np.isfinite(x) else None for x in sma]}, allow_nan=False))
+```
+
+使用前核对时间顺序、复权口径、缺失数据、单位和样本长度。多输入函数要求 OHLCV 数组按同一时间轴对齐。backtesting 策略可通过 `self.I(talib.SMA, self.data.Close, 20)` 注册指标。
+
+- `talib.MACD` 返回 `(macd, signal, hist)`，`hist = macd - signal`，不乘 2。
+- `talib.BBANDS` 返回 `(upper, middle, lower)`，默认使用 SMA 中轨和两倍总体标准差。
+- 暖机期输出 NaN；例如 SMA(20) 前 19 根、RSI(14) 前 14 根不可用。EMA、RSI 等按 TA-Lib 的种子与平滑规则计算，不等同于直接 pandas ewm。
+- NaN 输入可能影响后续输出，不擅自填零或把暖机值当成信号。持平序列的 RSI 在暖机后为 0，不是 50。
+- 指标可计算不证明策略有效。记录参数、TA-Lib 版本与数据依据；生成严格 JSON 时把非有限值转为 null。
+
+## backtesting 原生回测
+
+直接使用 `from backtesting import Backtest, Strategy`。继承 Strategy 定义 `init()` 和 `next()`，通过 `Backtest(data, 策略类, ...).run()` 运行。数据使用按时间升序的 OHLC DataFrame，可带 Volume，建议使用 DatetimeIndex；以当前安装版本的 API 为准。
+
+- 显式确定资金、手续费、价差、成交时点与仓位假设，不把库默认值当作投资规则。
+- 原生 Backtest 不自动提供 A 股 T+1、整手买入、涨跌停或交易日历约束。研究需要这些规则时，必须明确建模并验证；无法表达时说明限制，不能直接声称结果适用于该市场。
+- 按研究问题决定是否划分样本内/样本外及如何暖机，不默认套用固定回测流程。避免未来数据泄漏。
+- 原生结果可能包含 Series、DataFrame、时间和非有限值；按需要提取统计与交易记录，再转为可保存的数据，保留数据来源、参数及库版本。
+
+环境与许可信息见 [Python 说明](../../python/README.md)。

package/resources/skills/analysis-validation/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: analysis-validation
+description: 核验数据分析、计算结果和统计结论是否足以支持本次用途。用于交付前检查、数值差异排查、跨来源比较和分析复核，重点检查完整性、口径与推断依据。
+---
+
+# 分析核验
+
+围绕本次要支持的结论，优先核验足以改变判断的数据和计算。检查范围随结论风险和已发现的问题确定。
+
+## 确定核验依据
+
+读取已有结论及其实际数据、公式、源码和参数，确认对象范围、样本单位、比较基准和关键假设。缺少原始数据或计算入口时，区分能验证的部分与只能检查说明的部分。
+
+## 数据完整性与含义
+
+- 核对筛选、分页、截断及对象和期间覆盖。总量以已确认的覆盖范围为限；空结果能否支持“不存在”的判断，取决于查询覆盖。
+- 区分已确认零值、缺失、未查询、不可用和查询失败，按字段定义解释空值与零。
+- 汇总与明细不符时，先对齐期间、范围与定义。只有范围一致且明细完整时，明细重算才可验证汇总；冲突无法解释时保留两者与影响。
+- 按样本单位检查缺失、重复和关联前后的数量，区分同一对象的不同观测与重复计数。
+
+根据来源定义、时间语义和指标性质判断字段值是否异常，修正需有依据。
+
+## 口径与计算
+
+按任务选择能暴露错误的检查：
+
+| 对象 | 检查方法 |
+| --- | --- |
+| 比例与平均数 | 核对分子分母对应的对象与期间；分母为零时说明不可计算；分组平均按适当权重合并 |
+| 分项与总数 | 确认可加性，核对合计与差异；重叠分类、不同币种和非加性指标不能直接求和 |
+| 时间比较 | 对齐期间长度、完整程度与时区；区分数据发生时间和当时实际可获得时间 |
+| 单位与市场口径 | 核对币种、数量单位、复权和费用假设；转换需有依据，不隐含换算或市场规则 |
+| 关键计算 | 独立复算影响结论的值，或抽查原始记录与边界；只重跑同一段源码不能排除同一逻辑错误 |
+| 图表 | 核对图表与底层数据、标注、尺度及比较范围，避免显示方式改变读者判断 |
+
+输入或口径变化时，说明对可比性和结论的影响。复算依据保留实际命令、参数、必要输入与结果引用。
+
+## 推断与适用限制
+
+结论涉及样本推广、原因解释或预测时，检查样本选择与排除条件、样本量、幸存者偏差、替代解释和不确定性。多次比较、试验或参数筛选需结合完整选择过程评估结果。
+
+时间序列或预测研究需要核对信息在当时是否可知、训练与评估是否泄漏。样本外检验、成本和成交约束按研究用途确定；条件未验证时限制结论范围，不把库默认值当成实际市场条件。
+
+若主要问题是来源冲突或证据不足，使用 [research-evidence 技能](../research-evidence/SKILL.md) 处理相应判断。
+
+## 交付核验结论
+
+说明实际核验范围、发现的问题及其对结论的影响，判断结果足以支持本次用途、带限制可用，还是需要修正。指出关键缺口、适用条件与尚未核验的部分；修正后复查受影响结论。

package/resources/skills/project-maintenance/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: project-maintenance
+description: 维护项目结论、证据与可复用任务定义。用于资料更新、按既有口径复用任务、成果整理和项目结项。
+---
+
+# 项目整理与维护
+
+让资料呈现当前结论、适用条件、必要证据和真正未决的问题。重要结论或决策变化保留原因与原依据。
+
+根据本次变化更新当前任务、所属正文及实际受影响的引用。整体整理按用户指定范围进行。
+
+## 更新所属资料
+
+从根 AGENTS.md 和相关目录入口定位正文；入口未命中时，按主题、别名或项目名搜索。结合实际成果核对正文与入口，资料状态以对应证据为依据。
+
+按主题合并当前说明，保留理解、继续或复用任务所需的信息。新旧证据先核对对象、时期和条件；用已确认的新结论替换被取代的说明，同步相关说明与引用，保留未解决的冲突。
+
+历史证据与重要决策保留原有来源、时点、适用条件及必要理由，当前说明通过引用追溯。用户偏好与约束按其确认范围记录，推断与已确认约定分开。
+
+有跨任务价值的知识提炼到 knowledge/ 并引用项目证据，保留复用所需的条件。知识按主题命名，需要保留历史的研究和决策按日期与主题命名。
+
+根 AGENTS.md 用一棵 text 目录树维护资料索引，已确认的工作区约定单独保留。入口变化时更新现有树，展开到有资料的主题或项目目录；节点注释说明用途，未完成项目加 [TODO]，完成后移除。结论和未决事项留在正文，导航用链接引用。
+
+## 复用任务定义
+
+需要跨会话继续或重复执行的任务，在所属项目或长期事务中保存交付用途、必要证据、可接受限制和完成条件。目标变化时同步受影响的交付条件。
+
+重复分析或报告的定义按需包含指标公式与分母、数据来源、对象与筛选范围、期间与时区、分组与比较基准、输入和执行入口、产物位置及核验条件。单次输入与结果作为有时点的证据引用，与可复用定义分开。
+
+按上次口径重做时，读取已有定义，沿用已确认选择，并核对来源、版本与关键前提是否仍适用。更新报告使用本次期间与数据；复现历史结果使用指定输入。口径变化说明对可比性的影响，验证状态随新的验证证据更新。数值与计算核验见 [analysis-validation 技能](../analysis-validation/SKILL.md)。
+
+## 成果归集与清理
+
+用户要求整理或结项时，检查本次范围内的项目目录及 scratch/ 等临时产物位置。将有用信息并入正文，将必要证据与复现资料保存到对应 projects/<名称>/。
+
+长期保留支撑结论的最小充分资料：
+
+- 无法可靠恢复的输入快照、来源与数据口径。按能否再次取得同一份输入判断保存价值，而非来源是否仍可访问。
+- 复现所需的源码、命令、参数、必要环境说明及结果引用；数据注明对象、时点与单位。
+- 用户要求的最终成果与明细。
+
+完成归集并更新引用和复现路径后，清理已被吸收或不再需要、且不承担证据作用的临时产物。仍在使用、跨项目共享或归属与价值不明的文件暂留。清理仅限本次范围内的临时产物；正式资料、历史交易记录与备份保留，历史记录不改写。
+
+## 项目结项
+
+以已确认的目标和交付条件判断完成状态，核对必要成果、证据与复现入口确实可用。满足本次用途即可结项，已知限制留在正文；可选深化与必需工作分开。
+
+交付条件尚未满足时，记录具体缺口及其影响。完成状态、正文与证据一致后，同步项目入口和相关导航。

package/resources/skills/provider-connections/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: provider-connections
+description: 接入或修复原生 CLI/MCP，核对认证与可用性，维护精简的工作区工具手册。
+---
+
+# 原生工具接入
+
+从工作区 `providers/AGENTS.md`、对应 `<id>/GUIDE.md` 和用户给出的资料定位工具，优先复用已有接入。
+
+## CLI
+
+核对已安装版本，通过本次所需子命令的 help 确认参数、默认值和校验。排障时按需查看可信文档或源码。认证复用原生登录与 profile。
+
+## MCP
+
+用 `/mcp` 检查已有连接、认证、工具与配置来源。需要从 Bash 配置时，先读 `pi mcp --help` 及相关子命令帮助。
+
+新增连接默认只接入当前项目。从工作区根目录执行 `pi mcp add --local <server> ...`，写入 `.pi/mcp.json`；删除项目连接使用 `pi mcp remove --local <server>`。add/remove 未指定 `--local` 时修改当前 Pi agent dir 的 `mcp.json`，仅在用户明确要求跨项目使用时选择该范围。第三方 setup 同样采用项目配置；无法指定范围时，改用 Pi 原生项目配置。
+
+项目配置经 Pi 项目信任规则加载，同名条目可能覆盖用户级配置。修改前核对同名项，保留无关条目与已有用户级连接；迁移另按用户指定范围处理。认证使用原生登录或环境变量引用。
+
+外部修改配置后执行 `/reload`，再用 `/mcp` 核对实际配置来源和连接状态。当前工具 schema 通过原生工具搜索或 codemode 按需取得。
+
+## 验证与手册
+
+用本次获准的查询验证所需能力，将实际接口、时间、覆盖范围与结果依据保存在所属项目。区分配置已保存、连接可用和业务已验证。
+
+`providers/<id>/GUIDE.md` 面向当前使用，保留用途、原生入口、可信资料位置及适用版本。仅补充原生定义未说明、且影响正确使用的口径或限制；工具目录与参数细节从原生 help 和 schema 按需取得。
+
+更新时按主题合并，用已确认且适用的新结论替换过时说明，并同步示例。验证信息只保留影响当前使用的最新结论、时点与范围，详细和历史证据引用所属项目。
+
+`providers/AGENTS.md` 只做导航和已确认的选用约定。

package/resources/skills/research-evidence/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: research-evidence
+description: 判断多来源证据能支持哪些研究结论。用于证据综合、来源冲突、方案比较和关键假设验证。
+---
+
+# 研究证据与判断
+
+围绕本次问题形成可追溯的结论，说明证据支持到哪里、哪些条件会改变判断。
+
+## 选择证据
+
+明确要支持的主张、对象和时间范围，从已有证据中识别会影响判断的缺口，再补充检索。
+
+按主张选择来源：当前状态需要足够新的直接观测；历史事实需要对应时期的记录；规则需要适用版本；原因解释需要能区分替代解释的证据；方案比较需要一致的条件与评价依据。
+
+需要选择探索性研究方向、安排关键实验，或判断受阻研究是否应继续时，读[关键假设验证](references/hypothesis-checks.md)。
+
+## 核对证据与结论
+
+- 追溯关键主张的原始来源，读取支持该主张的上下文。转述、摘要和引用链中的多个页面不算多份独立证据；新增独立观测与重复转述分开判断。
+- 对关键证据保留定位信息、适用版本或时间、对象范围。区分事件发生时间、数据所属期间与取得时间；只记录影响本次使用的项。
+- 将观测与推断分开，说明从证据到结论所依赖的假设。
+- 检查可能推翻关键结论的证据与替代解释。找不到反证不等于已证实，尤其是在覆盖不足或查询失败时。
+- 来源冲突时，核对是否为不同版本、时期、样本或定义。能解释的差异分别说明；无法解释的冲突保留在结论中，不静默选一方或按来源数量表决。
+- 检索无结果时，核对名称、别名、筛选范围和来源是否可访问。只有查询覆盖足以支持时，才能作出不存在或未发生的判断。
+
+## 综合与交付
+
+按问题组织结论，关键结论附近给出来源或产物引用。说明支持及反对依据、重要假设、未决冲突和适用限制，用证据充分性解释置信程度。
+
+以本次交付用途判断证据是否足够。关键缺口阻止结论时，说明缺什么、影响哪部分及如何核实；条件化结论明确其待验证前提。
+
+涉及数值、数据比较或统计推断时，按需使用 [analysis-validation 技能](../analysis-validation/SKILL.md)。

package/resources/skills/research-evidence/references/hypothesis-checks.md

@@ -0,0 +1,33 @@
+# 关键假设验证
+
+用于探索性研究的选题、实验安排和受阻后的方向判断，尽早取得能改变决策的证据。
+
+## 找出决定方向的假设
+
+从目标和已有证据识别：哪些条件必须成立，结论才有意义；哪项不成立会改变方案；哪些检验依赖其他条件先成立。
+
+区分研究假设与方法前提。例如，策略是否具有样本外效果是研究假设；数据是否覆盖所需时期、能否按实际可知时间构造输入，是方法前提。
+
+对影响决策的假设，梳理现有支持与反对证据、尚不确定的条件、失败后果、可用检验及其成本。
+
+## 选择最有用的下一次检验
+
+优先选择不同结果会改变后续决策、能较早取得证据且成本适当的检验。必要时先核实数据与方法前提，再投入更大规模的实验。
+
+最小检验可以使用已有数据、较小样本或较简单的方法，但要说明它能够排除什么、仍不能证明什么。
+
+执行前明确与本次判断有关的内容：
+
+- 要区分的假设或替代解释，以及可观测结果。
+- 所需数据与资源、方法、比较基准和主要限制。
+- 哪些结果支持继续，哪些要求修改或停止，哪些仍无法区分假设。
+
+判据来自目标、领域依据或用户约束。看到结果后修改判据时，记录修改原因，并区分探索所得的解释与按原判据得到的结果。
+
+## 根据结果调整
+
+先判断检验是否有效执行。数据缺失、程序失败或方法不适用不等于研究假设被否定；代理指标改善也不自动证明最终目标达成。
+
+有效结果削弱关键假设时，比较继续排查、修改方法、缩小问题或停止该方向的价值。结果仍不确定时，根据下一项证据区分解释的能力决定是否继续。
+
+保留支撑方向判断的假设、判据、实际观测和产物引用。复用结果时保留检验条件与适用范围。

package/resources/templates/workspace-agents.md

@@ -0,0 +1,13 @@
+# 工作区资料入口
+
+## 目录树
+
+```text
+./
+├── areas/          # 长期目标、约束、建议、决策与复盘
+├── projects/       # 任务结论、必要数据与复现代码
+├── knowledge/      # 可复用知识、方法与参考资料
+├── providers/      # 能力提供方导航与手册
+├── scratch/        # 临时文件、运行环境与计算产物
+└── agents/         # coordinator.md 与 general-purpose.md 的职责补充
+```

package/scripts/README.md

@@ -0,0 +1,13 @@
+# 维护脚本
+
+## Python 环境准备
+
+`setup-python.py` 创建当前用户的共享 venv，按 requirements.lock 安装依赖。Personal Bot 加载后自动调用；也可独立执行，或通过 /pbot python setup 重试。
+
+脚本不接受解释器路径，不修改工作区资料或历史记录。路径、激活和失败处理见 [Python 说明](../python/README.md)。
+
+## 构建清理
+
+`clean-dist.mjs` 由 npm run build 调用，仅清理仓库内生成的 dist/，供 TypeScript 重新编译测试导入。
+
+本包不提供工作区升级命令或历史转换脚本。插件安装和更新由 Pi 原生包管理或用户维护的源码目录负责。