symkit-mcp 1.0.0__tar.gz

symkit_mcp-1.0.0/.editorconfig

@@ -0,0 +1,47 @@
+# EditorConfig - 跨編輯器格式一致性
+# https://editorconfig.org
+
+root = true
+
+# 所有檔案的預設設定
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+# Python
+[*.py]
+indent_size = 4
+max_line_length = 88
+
+# JavaScript / TypeScript
+[*.{js,jsx,ts,tsx}]
+indent_size = 2
+
+# JSON / YAML
+[*.{json,yml,yaml}]
+indent_size = 2
+
+# Markdown
+[*.md]
+trim_trailing_whitespace = false
+indent_size = 2
+
+# TOML
+[*.toml]
+indent_size = 4
+
+# Makefile (必須用 tab)
+[Makefile]
+indent_style = tab
+
+# Shell scripts
+[*.sh]
+indent_size = 2
+
+# Git
+[.git*]
+indent_size = 2

symkit_mcp-1.0.0/.env.example

@@ -0,0 +1,22 @@
+# 環境變數範例
+# 複製此檔案為 .env 並填入實際值
+
+# 應用程式設定
+APP_NAME=workspace251215
+APP_ENV=development
+APP_DEBUG=true
+
+# 資料庫設定
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=mydb
+DB_USER=user
+DB_PASSWORD=
+
+# API 金鑰（請勿提交真實金鑰）
+API_KEY=
+SECRET_KEY=
+
+# 外部服務
+# OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=

symkit_mcp-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,33 @@
+---
+name: 🐛 Bug 回报
+about: 回报一个问题
+title: '[Bug] '
+labels: bug
+assignees: ''
+---
+
+## 问题描述
+简要描述这个 bug。
+
+## 重现步骤
+1. 前往 '...'
+2. 点击 '...'
+3. 滚动到 '...'
+4. 看到错误
+
+## 预期行为
+描述你预期会发生什么。
+
+## 实际行为
+描述实际发生了什么。
+
+## 截屏
+如果适用，添加截屏来帮助解释你的问题。
+
+## 环境信息
+- OS: [例如 Windows 11]
+- 版本: [例如 0.1.0]
+- 其他相关信息
+
+## 额外备注
+其他关于这个问题的信息。

symkit_mcp-1.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: ✨ 功能建议
+about: 为此项目建议一个想法
+title: '[Feature] '
+labels: enhancement
+assignees: ''
+---
+
+## 这个功能建议是否与某个问题相关？
+清楚简洁地描述问题是什么。例如：「每次 [...] 时我都很沮丧」
+
+## 描述你想要的解决方案
+清楚简洁地描述你希望发生什么。
+
+## 描述你考虑过的替代方案
+清楚简洁地描述你考虑过的任何替代解决方案或功能。
+
+## 使用场景
+描述这个功能会在什么情况下被使用。
+
+## 额外备注
+关于此功能建议的任何其他信息或截屏。

symkit_mcp-1.0.0/.github/bylaws/ddd-architecture.md

@@ -0,0 +1,219 @@
+# 子法：DDD 架构规范
+
+> 父法：CONSTITUTION.md 第一章
+
+## 第 1 条：目录结构
+
+```
+src/
+├── Domain/                    # 领域层（内核）
+│   ├── Entities/              # 实体
+│   ├── ValueObjects/          # 值对象
+│   ├── Aggregates/            # 聚合根
+│   ├── DomainServices/        # 领域服务
+│   ├── DomainEvents/          # 领域事件
+│   └── Repositories/          # Repository 接口（仅接口）
+│
+├── Application/               # 应用层
+│   ├── UseCases/              # 用例
+│   ├── DTOs/                  # 数据传输对象
+│   ├── Services/              # 应用服务
+│   └── Interfaces/            # 外部服务接口
+│
+├── Infrastructure/            # 基础设施层
+│   ├── Persistence/           # DAL 数据访问
+│   │   ├── Repositories/      # Repository 实作
+│   │   ├── DbContext/         # 数据库上下文
+│   │   └── Migrations/        # 数据迁移
+│   ├── ExternalServices/      # 外部服务实作
+│   └── Messaging/             # 消息队列
+│
+└── Presentation/              # 呈现层
+    ├── API/                   # REST API
+    ├── GraphQL/               # GraphQL（可选）
+    └── CLI/                   # 命令行接口
+```
+
+## 第 2 条：依赖方向
+
+```
+Presentation → Application → Domain
+                    ↓
+              Infrastructure
+```
+
+- Domain 不依赖任何外层
+- Infrastructure 实作 Domain 定义的接口
+
+## 第 3 条：DAL 规范
+
+### 3.1 Repository 接口（在 Domain 层）
+```python
+# Domain/Repositories/IUserRepository.py
+class IUserRepository(ABC):
+    @abstractmethod
+    def get_by_id(self, id: UserId) -> Optional[User]: ...
+    
+    @abstractmethod
+    def save(self, user: User) -> None: ...
+```
+
+### 3.2 Repository 实作（在 Infrastructure 层）
+```python
+# Infrastructure/Persistence/Repositories/UserRepository.py
+class UserRepository(IUserRepository):
+    def __init__(self, db_context: DbContext):
+        self._db = db_context
+    
+    def get_by_id(self, id: UserId) -> Optional[User]:
+        # 实际数据库操作
+        ...
+```
+
+## 第 4 条：命名惯例
+
+| 类型 | 命名规则 | 范例 |
+|------|----------|------|
+| Entity | 名词单数 | `User`, `Order` |
+| Value Object | 描述性名词 | `EmailAddress`, `Money` |
+| Repository | `I{Entity}Repository` | `IUserRepository` |
+| Use Case | 动词 + 名词 | `CreateOrder`, `GetUserById` |
+| Domain Event | 过去式 | `OrderCreated`, `UserRegistered` |
+
+---
+
+## 第 5 条：模块化规范
+
+> 依据宪法第 7.3 条「主动重构原则」订定
+
+### 5.1 文件长度限制
+
+| 类型 | 建议上限 | 硬性上限 | 超过时动作 |
+|------|----------|----------|------------|
+| 单一文件 | 200 行 | 400 行 | 必须拆分 |
+| 类别 (Class) | 150 行 | 300 行 | 提取子类别或组合 |
+| 函数 (Function) | 30 行 | 50 行 | 提取私有方法 |
+| 模块 (目录) | 10 文件 | 15 文件 | 创建子模块 |
+
+### 5.2 复杂度指针
+
+```python
+# 圈复杂度 (Cyclomatic Complexity)
+# 建议 ≤ 10，硬性上限 15
+
+# ❌ 过于复杂
+def process_order(order):
+    if order.status == "pending":
+        if order.payment:
+            if order.payment.verified:
+                if order.items:
+                    for item in order.items:
+                        if item.in_stock:
+                            # ... 更多嵌套
+                            
+# ✅ 重构后
+def process_order(order):
+    validate_order_status(order)
+    verify_payment(order.payment)
+    process_items(order.items)
+```
+
+### 5.3 模块拆分策略
+
+当 Domain 模块过大时，按 **子领域** 拆分：
+
+```
+# Before: 单一 Domain
+src/Domain/
+├── Entities/
+│   ├── User.py
+│   ├── Order.py
+│   ├── Product.py
+│   ├── Payment.py
+│   └── Shipping.py  # 太多了！
+
+# After: 按子领域拆分
+src/Domain/
+├── Identity/           # 身份子领域
+│   ├── Entities/
+│   │   └── User.py
+│   └── ValueObjects/
+│       └── Email.py
+│
+├── Ordering/           # 订单子领域
+│   ├── Entities/
+│   │   └── Order.py
+│   ├── ValueObjects/
+│   │   └── OrderStatus.py
+│   └── DomainServices/
+│       └── OrderPricing.py
+│
+├── Catalog/            # 商品目录子领域
+│   └── Entities/
+│       └── Product.py
+│
+└── Shipping/           # 物流子领域
+    └── Entities/
+        └── Shipment.py
+```
+
+### 5.4 Application 层拆分
+
+按 **功能群组** 或 **用例** 拆分：
+
+```
+src/Application/
+├── Identity/           # 对应 Domain/Identity
+│   ├── Commands/
+│   │   ├── RegisterUser.py
+│   │   └── ChangePassword.py
+│   └── Queries/
+│       └── GetUserProfile.py
+│
+├── Ordering/           # 对应 Domain/Ordering
+│   ├── Commands/
+│   │   ├── CreateOrder.py
+│   │   └── CancelOrder.py
+│   └── Queries/
+│       └── GetOrderHistory.py
+```
+
+### 5.5 重构触发条件
+
+AI 应在以下情况 **主动建议** 重构：
+
+| 触发条件 | 建议动作 |
+|----------|----------|
+| 文件超过 200 行 | 「这个文件有点长，建议拆分成...」 |
+| 函数超过 30 行 | 「这个函数可以提取出...」 |
+| 圈复杂度 > 10 | 「这段逻辑较复杂，建议...」 |
+| 重复代码 | 「发现重复模式，建议抽取为...」 |
+| 跨层依赖 | 「这里违反了 DDD 分层，应该...」 |
+
+---
+
+## 第 6 条：重构安全网
+
+### 6.1 重构前必须
+
+1. ✅ 确保有测试覆盖（覆盖率 ≥ 70%）
+2. ✅ 运行现有测试确认通过
+3. ✅ 记录重构原因到 `decisionLog.md`
+
+### 6.2 重构后必须
+
+1. ✅ 运行全部测试
+2. ✅ 检查架构是否仍符合 DDD
+3. ✅ 更新相关文档
+4. ✅ 更新 ARCHITECTURE.md
+
+### 6.3 重构模式参考
+
+| 问题 | 重构模式 | 说明 |
+|------|----------|------|
+| 函数过长 | Extract Method | 提取私有方法 |
+| 类别过大 | Extract Class | 提取新类别 |
+| 重复代码 | Extract Superclass / Trait | 抽取共用逻辑 |
+| 过多参数 | Introduce Parameter Object | 创建参数对象 |
+| 条件过复杂 | Replace Conditional with Polymorphism | 用多态取代条件 |
+| 跨层依赖 | Dependency Injection | 依赖注入 |

symkit_mcp-1.0.0/.github/bylaws/git-workflow.md

@@ -0,0 +1,43 @@
+# 子法：Git 工作流规范
+
+> 父法：CONSTITUTION.md 第三章
+
+## 第 1 条：提交前检查清单
+
+依序运行以下步骤：
+
+| 顺序 | 项目 | 说明 | 可跳过 |
+|------|------|------|--------|
+| 1 | 运行测试 | `uv run pytest` | ❌ |
+| 2 | Lint 检查 | `uv run ruff check src/ tests/` | ❌ |
+| 3 | 类型检查 | `uv run mypy src/` | ❌ |
+| 4 | README 更新 | 如用户可见行为变更 | ✅ |
+| 5 | CHANGELOG 更新 | 如版本或功能变更 | ✅ |
+| 6 | ROADMAP 标记 | 如进度推进 | ✅ |
+
+## 第 2 条：Commit Message 格式
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Type 类型
+- `feat`: 新功能
+- `fix`: 修复
+- `docs`: 文档
+- `refactor`: 重构
+- `test`: 测试
+- `chore`: 杂项
+
+## 第 3 条：分支策略
+
+| 分支 | 用途 | 保护 |
+|------|------|------|
+| `main` | 稳定版本 | ✅ |
+| `develop` | 开发集成 | ✅ |
+| `feature/*` | 功能开发 | ❌ |
+| `hotfix/*` | 紧急修复 | ❌ |

symkit_mcp-1.0.0/.github/bylaws/python-environment.md

@@ -0,0 +1,251 @@
+# Python 环境管理子法
+
+> 依据宪法第 7.2 条「环境即代码」订定
+
+---
+
+## 第 1 条：套件管理器优先级
+
+```
+uv > pip-tools > pip
+```
+
+### 1.1 uv 优先原则
+1. **新项目必须使用 uv** 作为套件管理器
+2. uv 速度比 pip 快 10-100 倍
+3. 原生支持 lockfile 和虚拟环境
+
+### 1.2 降级条件
+仅在以下情况可使用 pip：
+- 旧项目迁移成本过高
+- CI 环境不支持 uv
+- 特殊依赖冲突
+
+---
+
+## 第 2 条：虚拟环境规范
+
+### 2.1 必须使用虚拟环境
+```bash
+# ✅ 正确
+uv venv
+source .venv/bin/activate  # Linux/macOS
+.venv\Scripts\activate     # Windows
+
+# ❌ 禁止全域安装
+pip install package  # 在系统 Python 中
+```
+
+### 2.2 虚拟环境位置
+```
+project/
+├── .venv/           # 虚拟环境（gitignore）
+├── pyproject.toml   # 项目配置
+└── uv.lock          # 依赖锁定（版控）
+```
+
+### 2.3 Python 版本
+- 本项目使用 Python 3.12+
+- 版本在 `pyproject.toml` 中明确指定
+
+---
+
+## 第 3 条：依赖管理
+
+### 3.1 文件结构
+```
+pyproject.toml       # 主要依赖定义（必须）
+uv.lock              # 依赖锁定档（必须，纳入版控）
+requirements.txt     # 兼容性导出（可选，CI 用）
+```
+
+### 3.2 pyproject.toml 范本
+```toml
+[project]
+name = "my-project"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.104.0",
+    "sqlalchemy>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+    "ruff>=0.1.0",
+    "mypy>=1.5.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+dev-dependencies = [
+    "pytest>=7.4.0",
+    "ruff>=0.1.0",
+]
+```
+
+### 3.3 常用 uv 指令
+```bash
+# 初始化项目
+uv init my-project
+cd my-project
+
+# 创建虚拟环境
+uv venv
+
+# 安装依赖
+uv pip install -e ".[dev]"
+uv sync  # 根据 uv.lock 同步
+
+# 添加依赖
+uv add fastapi
+uv add --dev pytest
+
+# 移除依赖
+uv remove package-name
+
+# 更新依赖
+uv lock --upgrade
+
+# 导出 requirements.txt（兼容 CI）
+uv pip compile pyproject.toml -o requirements.txt
+```
+
+---
+
+## 第 4 条：项目初始化流程
+
+### 4.1 新项目（使用 uv）
+```bash
+# 1. 创建项目
+uv init my-project
+cd my-project
+
+# 2. 设置 Python 版本
+uv python pin 3.12
+
+# 3. 安装开发依赖
+uv add --dev pytest ruff mypy
+
+# 4. 创建目录结构
+mkdir -p src/domain src/application src/infrastructure src/presentation
+mkdir -p tests/unit tests/integration tests/e2e
+touch src/__init__.py tests/__init__.py
+```
+
+### 4.2 现有项目迁移
+```bash
+# 1. 从 requirements.txt 迁移
+uv pip compile requirements.txt -o requirements.lock
+uv venv
+uv pip sync requirements.lock
+
+# 2. 创建 pyproject.toml
+uv init --no-workspace
+
+# 3. 迁移依赖
+uv add $(cat requirements.txt | grep -v "^#" | tr '\n' ' ')
+
+# 4. 锁定依赖
+uv lock
+```
+
+---
+
+## 第 5 条：CI/CD 集成
+
+### 5.1 GitHub Actions 使用 uv
+```yaml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      
+      - name: Set up Python
+        run: uv python install 3.11
+      
+      - name: Install dependencies
+        run: uv sync --all-extras
+      
+      - name: Run tests
+        run: uv run pytest
+```
+
+### 5.2 Docker 使用 uv
+```dockerfile
+FROM python:3.11-slim
+
+# 安装 uv（从官方映像拷贝）
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+COPY pyproject.toml uv.lock ./
+
+# 安装依赖（不使用虚拟环境）
+RUN uv pip install --system --no-cache -r pyproject.toml
+
+COPY . .
+CMD ["python", "-m", "src.main"]
+```
+
+### 5.3 uvx 工具运行（类似 npx）
+```bash
+# 临时运行工具（不安装）
+uvx ruff check .
+uvx black --check .
+uvx mypy src/
+
+# 运行特定版本
+uvx ruff@0.1.0 check .
+```
+
+---
+
+## 第 6 条：常见问题
+
+### Q1: uv 和 pip 可以混用吗？
+A: 不建议。混用可能导致依赖冲突。若必须，先用 `uv pip` 取代 `pip`。
+
+### Q2: 为什么不用 Poetry/Pipenv？
+A: uv 比 Poetry 快 10-100 倍，且与 pip 完全兼容。Poetry 的 resolver 较慢。
+
+### Q3: Windows 支持如何？
+A: uv 完整支持 Windows。安装：`powershell -c "irm https://astral.sh/uv/install.ps1 | iex"`
+
+### Q4: 如何处理私有套件？
+A: 在 `pyproject.toml` 中设置：
+```toml
+[tool.uv]
+index-url = "https://pypi.org/simple"
+extra-index-url = ["https://your-private-pypi.com/simple"]
+```
+
+---
+
+## 附录：快速参考卡
+
+| 操作 | uv 指令 | pip 对应 |
+|------|---------|----------|
+| 创建 venv | `uv venv` | `python -m venv .venv` |
+| 安装套件 | `uv add package` | `pip install package` |
+| 安装开发依赖 | `uv add --dev package` | `pip install package` |
+| 安装全部 | `uv sync` | `pip install -r requirements.txt` |
+| 更新 lock | `uv lock` | `pip-compile` |
+| 运行命令 | `uv run pytest` | `pytest` |
+| 查看依赖 | `uv pip list` | `pip list` |
+
+---
+
+*本子法版本：v1.0.0*
+*依据：宪法第 7.2 条*

symkit_mcp-1.0.0/.github/copilot-instructions.md

@@ -0,0 +1,73 @@
+# Copilot Custom Instructions
+
+This document provides project context for VS Code GitHub Copilot Agent Mode.
+
+---
+
+## Development Philosophy
+
+- Write or update design docs before changing behavior.
+- Add tests to `tests/` for any new logic.
+- Keep the Domain Layer free of external dependencies.
+
+---
+
+## Governance
+
+You must follow this hierarchy:
+
+1. **Constitution**: `CONSTITUTION.md` — top-level principles, must not be violated
+2. **Bylaws**: `.github/bylaws/*.md` — detailed rules
+
+---
+
+## Architecture Principles
+
+- **Domain-Driven Design (DDD)**
+- **Data Access Layer (DAL) must be independent**
+- Dependency direction: `Presentation → Application → Domain ← Infrastructure`
+
+See `.github/bylaws/ddd-architecture.md` for details.
+
+---
+
+## Python Environment (uv preferred)
+
+- Prefer **uv** for package and virtual environment management.
+- New projects must create `pyproject.toml` + `uv.lock`.
+- Do not install packages globally.
+
+```bash
+# Initialize environment
+uv venv
+uv sync --all-extras
+
+# Install dependencies
+uv add package-name
+uv add --dev pytest ruff
+```
+
+See `.github/bylaws/python-environment.md` for details.
+
+---
+
+## Git Workflow
+
+Before committing, run this checklist:
+
+1. ✅ Run tests: `uv run pytest`
+2. ✅ Run lint: `uv run ruff check src/ tests/`
+3. ✅ Run type check: `uv run mypy src/`
+4. 📖 Update README if user-facing behavior changed
+5. 📋 Update CHANGELOG if applicable
+6. 🗺️ Update ROADMAP if progress was made
+
+See `.github/bylaws/git-workflow.md` for details.
+
+---
+
+## Project Notes
+
+- SymKit is a **domain-agnostic** symbolic formula derivation engine.
+- It exposes **43 MCP tools** for math, derivation sessions, assumptions, verification, and orchestration.
+- Respond in Simplified Chinese when the user writes in Chinese.