内容
# 股票监控工具包
[English](README.md) | [简体中文](README.zh-CN.md)
一个本地优先、供应商中立的工具包，用于构建市场监控代理。它包含确定性的技术指标、共享模式、供应商合约、版本化的研究提示、可重复使用的代理技能和本地_stdio_MCP服务器。
本仓库是开放的核心。产品UI、私有观察列表、账户数据、商业评分权重、许可的数据适配器、机密和云服务故意保持在仓库之外。
> 仅限研究和教育使用。本项目不提供个性化的投资建议或交易执行。
## 包含内容
| 模块 | 目的 |
| --- | --- |
| `domain` | OHLCV条形图、观察列表、事件、策略设置、证据和报告的Zod模式 |
| `indicator-engine` | 纯粹的BBI、KDJ、MACD、成交量比率、交叉和可解释的策略函数 |
| `provider-contracts` | 用户提供的模型、市场数据、新闻、日历和预测市场适配器的接口 |
| `prompt-pack` | 版本化的盘前、盘后、事件预读和黑天鹅提示 |
| `workflow` | 连接观察列表、供应商、指标和模型的本地编排 |
| `mcp-server` | 本地_stdio_MCP工具、提示和资源 |
| `skills` | 四个可移植的代理技能，匹配研究工作流程 |
参见 [架构](docs/architecture.md) 了解开放/封闭边界。
## 快速开始
要求：Node.js 20 或更新版本。
```bash
npm install
npm run check
```
使用确定性引擎：
```ts
import { evaluateStrategy } from "@stock-monitoring-kit/indicator-engine";
const result = evaluateStrategy(bars, {
volumeRatioThreshold: 1.5,
kdjOversold: 20,
kdjOverbought: 80
});
console.log(result.signals, result.notes);
```
默认策略将收盘价低于BBI、异常成交量、KDJ极值和最新的MACD交叉视为独立证据。分数是透明的默认值，而不是专有的模型或交易推荐。
## 本地MCP服务器
通过_stdio_构建和运行：
```bash
npm run build
npm run mcp
```
克隆后的示例MCP客户端配置：
```json
{
"mcpServers": {
"stock-monitoring-kit": {
"command": "node",
"args": ["/absolute/path/to/stock-monitoring-kit/packages/mcp-server/dist/index.js"]
}
}
}
```
暴露的工具：
- `compute_technical_series`
- `evaluate_strategy`
- `render_research_prompt`
暴露的提示：
- `premarket-review`
- `postmarket-review`
- `event-preread`
- `black-swan-radar`
不需要HTTP服务器、云账户或项目拥有的API密钥。
## 引入您自己的供应商
在主机应用程序中实现 `provider-contracts` 中的接口。通过操作系统密钥链或其他主机控制的机密存储来解析API密钥；永远不要将它们嵌入到观察列表、提示、存储库或小程序包中。
```ts
import type { ModelProvider } from "@stock-monitoring-kit/provider-contracts";
export const localModelAdapter: ModelProvider = {
id: "my-provider",
async generate(request, credential) {
// 在主机应用程序中解析credential.id，调用所选的供应商，并返回文本。
throw new Error("在主机应用程序中实现");
}
};
```
## 技能
`skills/`下的每个目录都是一个独立的代理技能，带有 `SKILL.md` 和 `agents/openai.yaml`。仅安装或链接您需要的 工作流程。技能可以在可用时使用MCP工具，并在不可用时保留显式的备用定义。
## 设计原则
- 本地优先：用户观察列表和模型凭证保留在主机控制下。
- 证据优先：事实、共识、预测市场信号和推理保持独立。
- 确定性优先于生成性：计算是代码；模型解释和连接证据。
- 供应商中立：公共包定义合约，而不是许可或机密适配器。
- 可审计：提示版本、阈值、时间戳、来源和失效保持可见。
## 开发
```bash
npm run typecheck
npm test
npm run build
```
在打开拉取请求之前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。安全问题属于 [SECURITY.md](SECURITY.md) 中描述的流程。
## 许可证
Apache-2.0。参见 [LICENSE](LICENSE)。
