zcyclaw 0.1.0__tar.gz

zcyclaw-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+
+# 虚拟环境
+.venv/
+
+# 测试与缓存
+.pytest_cache/
+.ruff_cache/
+
+# 环境变量与敏感文件
+.env
+.env.*
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

zcyclaw-0.1.0/CLAUDE.md

@@ -0,0 +1,137 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 语言要求
+
+本项目所有沟通、文档、代码注释、commit message 均使用**中文**。
+
+## 项目概述
+
+**zyclaw**（政府采购 Agent）是一个独立于采购平台的政府采购智能顾问工具，基于 RAG 架构提供专业法规问答、采购方式推荐、价格查询、文档模板生成等功能。不绑定任何采购平台，核心开源。
+
+CLI 命令名：`zcyclaw`
+
+## 技术栈
+
+- **语言**: Python 3.11+
+- **CLI 框架**: Typer + Rich + prompt_toolkit
+- **配置管理**: Pydantic + pydantic-settings
+- **包管理**: uv（pyproject.toml + 分层extras + hatchling构建）
+- **向量库**: ChromaDB（嵌入式运行，PersistentClient本地持久化）
+- **Embedding**: 智谱API(首选) / fastembed(本地可选) / BGE-M3(高级可选)
+- **LLM**: DeepSeek / 智谱GLM(首选)，兼容OpenAI/Anthropic
+- **LLM Provider**: ProviderSpec注册表 + openai_compat统一后端（参考nanobot）
+- **RAG框架**: 自研（不用LangChain，体积可控、稳定、领域适配）
+- **日志**: loguru
+- **价格数据**: SQLite（结构化查询）
+- **爬虫**: 预构建数据(MVP) / requests增量(扩展) / Playwright(可选，非运行时依赖)
+- **文档生成**: python-docx + Jinja2
+- **构建系统**: hatchling
+- **打包分发**: uv + PyPI
+
+## 代码结构
+
+```
+src/zyclaw/
+├── __init__.py            # 版本号(从pyproject.toml读取)
+├── __main__.py            # 入口
+├── cli/
+│   ├── commands.py        # Typer命令定义
+│   └── stream.py          # 流式输出渲染
+├── config/
+│   ├── schema.py          # Pydantic配置模型
+│   ├── loader.py          # 配置加载
+│   └── paths.py           # 路径集中管理
+├── session.py             # 会话记忆管理
+├── history.py             # 历史记录管理
+├── rag/
+│   ├── loader.py          # 文档加载器
+│   ├── chunker.py         # 法规专用分块器(按条款/章节)
+│   ├── embeddings.py      # Embedding适配层
+│   ├── vector_store.py    # ChromaDB存储层
+│   └── retriever.py       # 检索器
+├── price/
+│   ├── store.py           # 历史成交价SQLite存储
+│   └── query.py           # 价格查询与分析
+├── crawler/
+│   └── gov_crawler.py     # 爬虫(可选模块)
+├── llm/
+│   ├── __init__.py        # 懒加载导出
+│   ├── base.py            # LLMProvider基类 + LLMResponse
+│   ├── registry.py        # ProviderSpec注册表
+│   ├── openai_compat.py   # OpenAI兼容后端(覆盖DeepSeek/智谱/通义/Ollama等)
+│   └── anthropic_provider.py  # Anthropic独立后端
+├── template/
+│   ├── doc_generator.py   # Word文档生成
+│   └── *.jinja2           # 各类文档模板
+└── types.py               # 类型定义
+```
+
+## 开发命令
+
+```bash
+# 安装依赖
+uv sync
+
+# 运行 CLI
+uv run zcyclaw
+
+# 构建
+uv build
+
+# 发布到 PyPI
+uv publish
+
+# 运行测试
+uv run pytest
+
+# 免安装直接运行
+uvx zyclaw ask "询价采购需要满足什么条件？"
+```
+
+## 核心设计原则
+
+1. **专业准确优先**: 所有回答必须标注法条来源，可追溯，不知道就直说
+2. **隐私第一**: 所有数据本地存储，API Key 不经第三方，请求直连 LLM 厂商
+3. **开箱即用**: 预构建法规数据包首次运行下载，核心功能安装即用
+4. **渐进式功能**: 先核心问答，再逐步扩展
+5. **国产优先**: LLM 和 Embedding 优先支持国产模型（DeepSeek/智谱/通义）
+6. **轻量安装**: 核心包最小化，扩展功能通过 extras 按需安装
+7. **参考 nanobot 架构**: Provider 注册表 + Pydantic 配置 + 懒加载 + 路径集中管理
+
+## 分层安装
+
+```bash
+uv tool install zyclaw                          # 最小安装
+uv tool install "zcyclaw[deepseek,zhipu]"        # 国产模型支持
+uv tool install "zcyclaw[full]"                  # 完整安装
+```
+
+## 配置
+
+配置文件位置：`~/.zcyclaw/config.json`
+采用 Pydantic + pydantic-settings，支持环境变量覆盖（`ZCYCLAW_PROVIDERS__DEEPSEEK__API_KEY=xxx`）
+
+## 分阶段开发计划
+
+- **Phase 1**: CLI框架 + RAG问答(自研) + 国产模型支持 + 预构建数据包
+- **Phase 2**: 价格查询 + 文档模板生成 + 合规计算 + 历史管理
+- **Phase 3**: 供应商功能 + 可选爬虫 + 法规追踪 + TUI/Web UI
+
+## 架构分层
+
+用户交互层(CLI→TUI→Web) → 会话记忆层 → RAG知识检索层(ChromaDB+自研) → 结构化数据层(SQLite) → 数据更新层(预构建→增量→可选爬虫) → LLM推理生成层
+
+## 关键决策
+
+- **Typer 替代 Click**: 更现代的CLI框架，自动类型推断和help生成
+- **Pydantic 配置**: 类型安全 + 环境变量自动解析，参考nanobot
+- **ProviderSpec注册表**: 新增厂商只需加一条Spec + 一个Config字段，参考nanobot
+- **openai_compat统一后端**: 绝大多数国产模型兼容OpenAI协议，避免为每个厂商写适配器
+- **懒加载**: 用户只装了DeepSeek就不导入Anthropic SDK，减少启动时间和内存
+- **不用LangChain**: 依赖链重(+200MB)、breaking changes频繁，自研RAG核心代码量可控
+- **Playwright非运行时依赖**: 安装体积200MB+，仅作可选"zcyclaw[crawler]`扩展
+- **国产模型优先**: 目标用户在国内，OpenAI/Anthropic访问不稳定
+- **预构建数据包**: 首次运行从CDN下载，避免本地构建耗时
+- **loguru替代logging**: 更简洁的日志库，开箱即用

zcyclaw-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zyclaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zcyclaw-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: zcyclaw
+Version: 0.1.0
+Summary: 政府采购智能顾问 - 基于RAG的法规问答CLI工具
+Project-URL: Homepage, https://github.com/brucehuu/zyclaw
+Project-URL: Repository, https://github.com/brucehuu/zyclaw
+Project-URL: Issues, https://github.com/brucehuu/zyclaw/issues
+Author: zyclaw
+License: MIT
+License-File: LICENSE
+Keywords: ai-agent,cli,government-procurement,rag
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.11
+Requires-Dist: chromadb>=0.5
+Requires-Dist: httpx>=0.27
+Requires-Dist: loguru>=0.7
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-docx>=1.2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30; extra == 'anthropic'
+Provides-Extra: crawler
+Requires-Dist: playwright>=1.40; extra == 'crawler'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: fastembed
+Requires-Dist: fastembed>=0.4; extra == 'fastembed'
+Provides-Extra: full
+Requires-Dist: anthropic>=0.30; extra == 'full'
+Requires-Dist: fastembed>=0.4; extra == 'full'
+Description-Content-Type: text/markdown
+
+# zyclaw
+
+政府采购智能顾问 — 基于 RAG 的法规问答 CLI 工具。
+
+独立于采购平台，基于中国政府采购法律法规提供专业问答、采购方式推荐等功能。核心开源，数据本地存储，隐私第一。
+
+## 功能
+
+- **法规智能问答**：基于 16 部核心法规（766 条法条），回答自动标注法条来源
+- **流式输出**：token-by-token 逐字显示，体验流畅
+- **多 LLM 支持**：DeepSeek / 智谱 GLM / 通义千问 / Moonshot / OpenAI / Ollama / Anthropic
+- **开箱即用**：预构建法规数据随包分发，安装即可使用
+- **本地优先**：向量库、配置、日志全部本地存储，API Key 直连 LLM 厂商
+
+## 快速开始
+
+```bash
+# 安装
+uv tool install zyclaw
+
+# 或使用 pip
+pip install zcyclaw
+
+# 初始化配置（选择 LLM 提供商 + 输入 API Key）
+zcyclaw init
+
+# 单次问答
+zcyclaw ask "询价采购需要满足什么条件？"
+
+# 交互式多轮问答
+zcyclaw ask -i
+
+# 更新法规数据
+zcyclaw update
+
+# 查看数据统计
+zcyclaw stats
+```
+
+## 配置
+
+配置文件位置：`~/.zcyclaw/config.json`
+
+支持环境变量覆盖，前缀 `ZCYCLAW_`，双下划线分隔嵌套：
+
+```bash
+export ZCYCLAW_PROVIDERS__DEEPSEEK__API_KEY=sk-xxx
+export ZCYCLAW_DEFAULT_PROVIDER=deepseek
+```
+
+## 可选安装
+
+```bash
+# Anthropic 后端支持
+uv tool install "zcyclaw[anthropic]"
+
+# 本地 Embedding（fastembed/BGE-M3）
+uv tool install "zcyclaw[fastembed]"
+
+# 完整安装
+uv tool install "zcyclaw[full]"
+```
+
+## 内置法规
+
+| 效力层级 | 法规 |
+|----------|------|
+| 法律 | 政府采购法、招标投标法 |
+| 行政法规 | 政府采购法实施条例、招标投标法实施条例 |
+| 部门规章 | 货物和服务招标投标管理办法、非招标采购方式管理办法、竞争性磋商采购方式管理暂行办法、框架协议采购方式管理暂行办法、促进中小企业发展管理办法、需求管理办法、信息公开办法、评审专家管理办法、进口产品管理办法、代理机构管理暂行办法、政府和社会资本合作项目政府采购管理办法、关于促进政府采购公平竞争优化营商环境的通知 |
+
+## 技术栈
+
+Python 3.11+ / Typer / Rich / Pydantic / ChromaDB / httpx / loguru
+
+## 许可证
+
+MIT License

zcyclaw-0.1.0/README.md

@@ -0,0 +1,78 @@
+# zyclaw
+
+政府采购智能顾问 — 基于 RAG 的法规问答 CLI 工具。
+
+独立于采购平台，基于中国政府采购法律法规提供专业问答、采购方式推荐等功能。核心开源，数据本地存储，隐私第一。
+
+## 功能
+
+- **法规智能问答**：基于 16 部核心法规（766 条法条），回答自动标注法条来源
+- **流式输出**：token-by-token 逐字显示，体验流畅
+- **多 LLM 支持**：DeepSeek / 智谱 GLM / 通义千问 / Moonshot / OpenAI / Ollama / Anthropic
+- **开箱即用**：预构建法规数据随包分发，安装即可使用
+- **本地优先**：向量库、配置、日志全部本地存储，API Key 直连 LLM 厂商
+
+## 快速开始
+
+```bash
+# 安装
+uv tool install zyclaw
+
+# 或使用 pip
+pip install zcyclaw
+
+# 初始化配置（选择 LLM 提供商 + 输入 API Key）
+zcyclaw init
+
+# 单次问答
+zcyclaw ask "询价采购需要满足什么条件？"
+
+# 交互式多轮问答
+zcyclaw ask -i
+
+# 更新法规数据
+zcyclaw update
+
+# 查看数据统计
+zcyclaw stats
+```
+
+## 配置
+
+配置文件位置：`~/.zcyclaw/config.json`
+
+支持环境变量覆盖，前缀 `ZCYCLAW_`，双下划线分隔嵌套：
+
+```bash
+export ZCYCLAW_PROVIDERS__DEEPSEEK__API_KEY=sk-xxx
+export ZCYCLAW_DEFAULT_PROVIDER=deepseek
+```
+
+## 可选安装
+
+```bash
+# Anthropic 后端支持
+uv tool install "zcyclaw[anthropic]"
+
+# 本地 Embedding（fastembed/BGE-M3）
+uv tool install "zcyclaw[fastembed]"
+
+# 完整安装
+uv tool install "zcyclaw[full]"
+```
+
+## 内置法规
+
+| 效力层级 | 法规 |
+|----------|------|
+| 法律 | 政府采购法、招标投标法 |
+| 行政法规 | 政府采购法实施条例、招标投标法实施条例 |
+| 部门规章 | 货物和服务招标投标管理办法、非招标采购方式管理办法、竞争性磋商采购方式管理暂行办法、框架协议采购方式管理暂行办法、促进中小企业发展管理办法、需求管理办法、信息公开办法、评审专家管理办法、进口产品管理办法、代理机构管理暂行办法、政府和社会资本合作项目政府采购管理办法、关于促进政府采购公平竞争优化营商环境的通知 |
+
+## 技术栈
+
+Python 3.11+ / Typer / Rich / Pydantic / ChromaDB / httpx / loguru
+
+## 许可证
+
+MIT License