monadomics 0.2.3__tar.gz

monadomics-0.2.3/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

monadomics-0.2.3/MANIFEST.in

@@ -0,0 +1,6 @@
+recursive-include src/monadomics/r *.R
+recursive-include workbuddy-connector *.json *.md *.svg
+recursive-include tests *.py *.sh *.csv *.R
+recursive-include docs *.md
+include scripts/build_workbuddy_connector.py
+include install.py

monadomics-0.2.3/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: monadomics
+Version: 0.2.3
+Summary: Local R-backed bioinformatics workflows for WorkBuddy
+Author: MonadOmics
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/daisyluvr42/monad_omicskit
+Keywords: bioinformatics,omics,workbuddy,bioconductor
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# MonadOmics 生信工具箱
+
+MonadOmics 0.2.3 把原 Omics Skill + MCP 整理为 **一个本地 CLI + 一个主 Skill**，另附 WorkBuddy 市场连接器包。本机 Python CLI 调用 R，保留差异表达、功能富集、组学作图和预后建模等 21 项能力；数值和图来自实际计算。
+
+**支持 GitHub 安装和 PyPI CLI 安装。** GitHub 安装器直接部署 CLI 运行文件和主 Skill；PyPI 提供 `monadomics` 命令，WorkBuddy 市场连接器另附主 Skill。市场安装仍需通过腾讯审核。
+
+## 能做什么
+
+| 工作 | 实现 |
+|---|---|
+| 矩阵与样本检查 | 数据类型、样本注释、PCA |
+| 差异表达 | DESeq2、edgeR、limma、limma-voom、协变量、多重校正 |
+| 功能富集 | GO、KEGG、Reactome、GSEA、GSVA/ssGSEA |
+| 组学图 | PCA、火山图、热图、2–4 组 Venn 与区域成员表 |
+| 预后模型 | LASSO-Cox、风险评分、KM、时间依赖 ROC、列线图、校准、DCA |
+
+用户可以提供检测公司的结果文件夹、压缩包或完整数据表，附已有报告和样本分组说明。主 Skill 先扫描材料与已有对话，集中询问影响当前分析的必要信息缺口，再指导模型使用宿主工具提取规范表格，保存后与原表及报告校验，通过后调用分析。用户补充与来源记入 `input-check.md`，后续复用；仅暂停受缺失信息影响的步骤。这里只统一文件和字段格式，不改变表达量单位或做统计归一化；详见 [输入整理规范](https://github.com/daisyluvr42/monad_omicskit/blob/main/workbuddy-connector/skills/monadomics-analysis/references/data-preparation.md)。CLI 本身仍接收整理后的数据，不新增厂商导入命令。
+
+这不是完整的 GEO/TCGA 下载器或 Seurat 单细胞流水线。单细胞 pseudobulk count 可以进入差异分析。
+
+## GitHub 安装和第一次运行
+
+需要 Python 3.11+；实际分析还需要 R 4.2+ 和对应 R 包。使用 GitHub CLI 克隆仓库并安装：
+
+```bash
+gh repo clone https://github.com/daisyluvr42/monad_omicskit.git
+cd monad_omicskit
+python3 install.py install
+python3 install.py run --version
+python3 install.py run doctor --group deg
+```
+
+没有 `gh` 时，第一步使用 `git clone https://github.com/daisyluvr42/monad_omicskit.git`。Windows 将 `python3` 换为 `py -3.12`。安装器只使用 Python 标准库，不下载 Python 依赖，也不自动安装 R/Bioconductor。
+
+安装位置为 `~/.workbuddy/skills/monadomics-analysis`，包含主 Skill、输入校验规范和 Python/R 运行文件。安装后的 Skill 会注明本机解释器与 CLI 的完整路径，WorkBuddy 无需依赖终端 PATH 或激活虚拟环境。安装时使用的 Python 解释器需继续保留。安装后刷新技能或重启 WorkBuddy，再用自然语言提交分析任务。
+
+### 从旧 MCP 版升级
+
+在原仓库目录执行下面的命令，不再使用旧的 `mcp/omics.py update workbuddy`：
+
+```bash
+git pull --ff-only
+python3 install.py install
+```
+
+安装器会备份原 `omics-analysis` Skill，并停用配置中指向旧 `mcp/omics_mcp.py` 的 `omics` MCP；其他连接器保持不变。旧配置和 Skill 保存在 `~/.workbuddy/monadomics-backups/`，分析数据与 R 包保留。重启 WorkBuddy 使旧 MCP 停用生效。
+
+### 更新与卸载
+
+```bash
+python3 install.py update
+python3 install.py uninstall
+```
+
+`update` 先检查仓库没有未保存的改动，再执行 `git pull --ff-only`，使用拉取后的新安装器刷新 CLI 与 Skill。下载源码压缩包的用户应下载新包后执行 `install`。卸载将本 kit 的 Skill 和运行文件移入备份目录，不删除 R 包、分析输出，也不会自动重新启用旧 MCP。
+
+如需隔离安装位置，使用 `python3 install.py --workbuddy-dir <目录> install`，之后的 `run`/`update`/`uninstall` 使用同一选项；默认位置无需指定。
+
+### 准备分析环境
+
+R 本体从 [CRAN](https://cran.r-project.org/) 或对应系统渠道准备。R 不在 PATH 时，将 `OMICS_RSCRIPT` 设为实际 Rscript/Rscript.exe 的绝对路径。macOS 会额外识别官方 R 和常见 Homebrew 安装位置。
+
+R 包与连接器初始化分开：
+
+```bash
+python3 install.py run setup-r deg
+python3 install.py run doctor --group deg
+```
+
+模块：`core`、`deg`、`enrich`、`plot`、`survival`、`all`。setup-r 把缺失依赖安装到 R 的个人库 `R_LIBS_USER`，安装日志在 stderr；doctor 不安装任何东西。首次 Bioconductor 安装可能较久，不放进 WorkBuddy init。系统编译库仍由操作系统准备；未安装完不能进行相应分析。
+
+## 调用分析
+
+将参数保存为 `deg.json`，例如：
+
+```json
+{
+  "method": "deseq2",
+  "matrix_type": "counts",
+  "matrix_path": "counts.csv",
+  "coldata_path": "samples.csv",
+  "group_column": "group",
+  "treat": "disease",
+  "control": "control",
+  "output_name": "disease_vs_control"
+}
+```
+
+```bash
+python3 install.py run deg --params deg.json --output-dir analysis-results
+python3 install.py run schema enrich
+python3 install.py run capabilities
+```
+
+- `deg`、`enrich`、`plot`、`survival` 均读取 `--params` 指定的 JSON 对象；`--params -` 读取标准输入。
+- 相对输入路径以命令工作目录为准；矩阵为基因×样本，首列基因 ID；样本表首列样本 ID。支持 CSV/TSV 或 schema 说明的内联记录，不直接读取 XLSX。
+- 分析成功：退出 0，stdout 为 `ok: true` 的 JSON，含结果与文件路径。分析失败：退出 1，JSON 含 `ok: false` 与错误信息。命令用法错误：退出 2。
+- `--output-dir` 控制产物目录；默认 `~/.workbuddy/workspace/omics`，也支持 `OMICS_OUTPUT_DIR`。
+- 分析默认超时 900 秒，作图 600 秒；可按需要传 `--timeout`。长任务使用宿主命令进程的等待能力，不反复重跑同一分析。
+
+参数和场景例子见 [主 Skill](https://github.com/daisyluvr42/monad_omicskit/blob/main/workbuddy-connector/skills/monadomics-analysis/SKILL.md) 及其 references。
+
+Skill 在分析前、工具返回后、交付前三个节点核对语义和依据，复用现有参数与结果记录，不要求逐步审批。工具自动拒绝重复/空 ID、缺失样本注释及不可估计的设计；DEG 返回实际两组拟合范围，显式提供 `species`/`id_type` 时附数据库注释。富集区分 ID 映射数与有效注释分母，零显著结果可以正常交付。矩阵重复基因不会再静默求和或择一，需在数据清洗时有依据地处理。
+
+## PyPI 安装与 WorkBuddy 市场包
+
+在 Python 3.11+ 虚拟环境中安装固定版本，获得 PATH 中的 `monadomics` 命令；其参数与 `python3 install.py run` 一致。GitHub 安装不需要这一步。
+
+```bash
+python -m pip install --upgrade monadomics==0.2.3
+monadomics --version
+monadomics doctor --group deg
+```
+
+PyPI 包包含 Python CLI 和 R 分析脚本，不会自动安装 WorkBuddy Skill、R 本体或 Bioconductor 依赖。需要在 WorkBuddy 中使用时，选择上面的 GitHub 安装方式或经审核上架的市场连接器。R 包可在 R 就绪后执行 `monadomics setup-r deg` 安装。
+
+```text
+workbuddy-connector/
+├── connector-meta.json
+├── cli.json
+├── icon.svg
+└── skills/monadomics-analysis/
+    ├── SKILL.md
+    └── references/
+```
+
+`cli.json` 声明 WorkBuddy 托管 Python 3.12，最低 WorkBuddy 5.0.0；macOS/Linux/Windows 都使用固定版本的 pip 安装命令。无登录和 API Key，不配置虚构的 auth/status/unAuth。连接器只声明 CLI，不混入 MCP。
+
+```bash
+python -m pip install build
+python -m build
+python scripts/build_workbuddy_connector.py
+```
+
+生成 Python wheel、sdist，以及 `dist/monadomics-workbuddy-0.2.3.zip`。ZIP 根目录直接包含 connector-meta.json 等文件，符合 [WorkBuddy 连接器规范](https://open.workbuddy.cn/en/docs/connector) 和 [Skill 规范](https://open.workbuddy.cn/en/docs/skill)。
+
+**市场连接器锁定 PyPI 上的 `monadomics==0.2.3`，并需通过 WorkBuddy 审核。** PyPI 发布、本地 wheel 安装和 ZIP 校验均不代表已经在 WorkBuddy 市场上架；当前验证范围见 [RELEASE.md](https://github.com/daisyluvr42/monad_omicskit/blob/main/docs/RELEASE.md)。提交 WorkBuddy 的是连接器 ZIP，Python 包由 init 从 PyPI 安装。GitHub 路线直接部署源码，不依赖该市场初始化命令。
+
+旧 0.1 MCP 代码在 Git 历史中保留。0.2 使用新 Skill `monadomics-analysis`，旧版迁移由上述 GitHub 安装器完成。
+
+## 科学与数据边界
+
+- 原始 count 与标准化/log2 表达必须区分；`normalized` 不代表已采用适当 log2 尺度。DESeq2/edgeR 拒绝非原始 count。
+- 富集需确认物种、ID 类型和背景。GSEA 需要完整排序列表；GSVA/ssGSEA 需要提供来源明确的 `gene_sets`，不会自动下载默认基因集。
+- 基因、通路、P 值、系数不能由模型编造。报告未映射 ID、校正方法和工具警告；富集是关联证据。
+- 生存时间单位、事件编码、候选变量来源须明确。训练集 C-index/AUC 不代表外部验证或临床有效性。
+- 本地计算不上传表达/生存表至另一分析服务器；R 安装、KEGG 等网络功能会访问公共资源。宿主读取的对话和工具输出按 WorkBuddy 自身规则处理。
+
+## 验证
+
+```bash
+python -m pip install -e .
+OMICS_OUTPUT_DIR="$PWD/test-output" python -m unittest discover -s tests -v
+bash tests/smoke_cli.sh
+python tests/run_acceptance.py --output-dir test-output/acceptance
+```
+
+测试数据均为固定种子的合成数据，不是公开患者数据或生物学发现。完整测试需要对应 R 包；缺包时后端测试会明确 skip，不能把 skip 当作分析通过。独立 wheel 验收应使用新环境安装 wheel，从源码目录之外运行 `tests/run_acceptance.py`，并检查生成的表和图。
+
+## 许可证
+
+Copyright 2026 MonadOmics contributors.
+
+MonadOmics 的项目代码、主 Skill 和随附文档采用 [Apache License 2.0](https://github.com/daisyluvr42/monad_omicskit/blob/main/LICENSE)。完整许可证随 Python wheel、源码包和 WorkBuddy 连接器 ZIP 分发；GitHub 安装器也会保留许可证。R、Bioconductor 及其他外部依赖和数据仍遵循各自的许可证。

monadomics-0.2.3/README.md

@@ -0,0 +1,164 @@
+# MonadOmics 生信工具箱
+
+MonadOmics 0.2.3 把原 Omics Skill + MCP 整理为 **一个本地 CLI + 一个主 Skill**，另附 WorkBuddy 市场连接器包。本机 Python CLI 调用 R，保留差异表达、功能富集、组学作图和预后建模等 21 项能力；数值和图来自实际计算。
+
+**支持 GitHub 安装和 PyPI CLI 安装。** GitHub 安装器直接部署 CLI 运行文件和主 Skill；PyPI 提供 `monadomics` 命令，WorkBuddy 市场连接器另附主 Skill。市场安装仍需通过腾讯审核。
+
+## 能做什么
+
+| 工作 | 实现 |
+|---|---|
+| 矩阵与样本检查 | 数据类型、样本注释、PCA |
+| 差异表达 | DESeq2、edgeR、limma、limma-voom、协变量、多重校正 |
+| 功能富集 | GO、KEGG、Reactome、GSEA、GSVA/ssGSEA |
+| 组学图 | PCA、火山图、热图、2–4 组 Venn 与区域成员表 |
+| 预后模型 | LASSO-Cox、风险评分、KM、时间依赖 ROC、列线图、校准、DCA |
+
+用户可以提供检测公司的结果文件夹、压缩包或完整数据表，附已有报告和样本分组说明。主 Skill 先扫描材料与已有对话，集中询问影响当前分析的必要信息缺口，再指导模型使用宿主工具提取规范表格，保存后与原表及报告校验，通过后调用分析。用户补充与来源记入 `input-check.md`，后续复用；仅暂停受缺失信息影响的步骤。这里只统一文件和字段格式，不改变表达量单位或做统计归一化；详见 [输入整理规范](https://github.com/daisyluvr42/monad_omicskit/blob/main/workbuddy-connector/skills/monadomics-analysis/references/data-preparation.md)。CLI 本身仍接收整理后的数据，不新增厂商导入命令。
+
+这不是完整的 GEO/TCGA 下载器或 Seurat 单细胞流水线。单细胞 pseudobulk count 可以进入差异分析。
+
+## GitHub 安装和第一次运行
+
+需要 Python 3.11+；实际分析还需要 R 4.2+ 和对应 R 包。使用 GitHub CLI 克隆仓库并安装：
+
+```bash
+gh repo clone https://github.com/daisyluvr42/monad_omicskit.git
+cd monad_omicskit
+python3 install.py install
+python3 install.py run --version
+python3 install.py run doctor --group deg
+```
+
+没有 `gh` 时，第一步使用 `git clone https://github.com/daisyluvr42/monad_omicskit.git`。Windows 将 `python3` 换为 `py -3.12`。安装器只使用 Python 标准库，不下载 Python 依赖，也不自动安装 R/Bioconductor。
+
+安装位置为 `~/.workbuddy/skills/monadomics-analysis`，包含主 Skill、输入校验规范和 Python/R 运行文件。安装后的 Skill 会注明本机解释器与 CLI 的完整路径，WorkBuddy 无需依赖终端 PATH 或激活虚拟环境。安装时使用的 Python 解释器需继续保留。安装后刷新技能或重启 WorkBuddy，再用自然语言提交分析任务。
+
+### 从旧 MCP 版升级
+
+在原仓库目录执行下面的命令，不再使用旧的 `mcp/omics.py update workbuddy`：
+
+```bash
+git pull --ff-only
+python3 install.py install
+```
+
+安装器会备份原 `omics-analysis` Skill，并停用配置中指向旧 `mcp/omics_mcp.py` 的 `omics` MCP；其他连接器保持不变。旧配置和 Skill 保存在 `~/.workbuddy/monadomics-backups/`，分析数据与 R 包保留。重启 WorkBuddy 使旧 MCP 停用生效。
+
+### 更新与卸载
+
+```bash
+python3 install.py update
+python3 install.py uninstall
+```
+
+`update` 先检查仓库没有未保存的改动，再执行 `git pull --ff-only`，使用拉取后的新安装器刷新 CLI 与 Skill。下载源码压缩包的用户应下载新包后执行 `install`。卸载将本 kit 的 Skill 和运行文件移入备份目录，不删除 R 包、分析输出，也不会自动重新启用旧 MCP。
+
+如需隔离安装位置，使用 `python3 install.py --workbuddy-dir <目录> install`，之后的 `run`/`update`/`uninstall` 使用同一选项；默认位置无需指定。
+
+### 准备分析环境
+
+R 本体从 [CRAN](https://cran.r-project.org/) 或对应系统渠道准备。R 不在 PATH 时，将 `OMICS_RSCRIPT` 设为实际 Rscript/Rscript.exe 的绝对路径。macOS 会额外识别官方 R 和常见 Homebrew 安装位置。
+
+R 包与连接器初始化分开：
+
+```bash
+python3 install.py run setup-r deg
+python3 install.py run doctor --group deg
+```
+
+模块：`core`、`deg`、`enrich`、`plot`、`survival`、`all`。setup-r 把缺失依赖安装到 R 的个人库 `R_LIBS_USER`，安装日志在 stderr；doctor 不安装任何东西。首次 Bioconductor 安装可能较久，不放进 WorkBuddy init。系统编译库仍由操作系统准备；未安装完不能进行相应分析。
+
+## 调用分析
+
+将参数保存为 `deg.json`，例如：
+
+```json
+{
+  "method": "deseq2",
+  "matrix_type": "counts",
+  "matrix_path": "counts.csv",
+  "coldata_path": "samples.csv",
+  "group_column": "group",
+  "treat": "disease",
+  "control": "control",
+  "output_name": "disease_vs_control"
+}
+```
+
+```bash
+python3 install.py run deg --params deg.json --output-dir analysis-results
+python3 install.py run schema enrich
+python3 install.py run capabilities
+```
+
+- `deg`、`enrich`、`plot`、`survival` 均读取 `--params` 指定的 JSON 对象；`--params -` 读取标准输入。
+- 相对输入路径以命令工作目录为准；矩阵为基因×样本，首列基因 ID；样本表首列样本 ID。支持 CSV/TSV 或 schema 说明的内联记录，不直接读取 XLSX。
+- 分析成功：退出 0，stdout 为 `ok: true` 的 JSON，含结果与文件路径。分析失败：退出 1，JSON 含 `ok: false` 与错误信息。命令用法错误：退出 2。
+- `--output-dir` 控制产物目录；默认 `~/.workbuddy/workspace/omics`，也支持 `OMICS_OUTPUT_DIR`。
+- 分析默认超时 900 秒，作图 600 秒；可按需要传 `--timeout`。长任务使用宿主命令进程的等待能力，不反复重跑同一分析。
+
+参数和场景例子见 [主 Skill](https://github.com/daisyluvr42/monad_omicskit/blob/main/workbuddy-connector/skills/monadomics-analysis/SKILL.md) 及其 references。
+
+Skill 在分析前、工具返回后、交付前三个节点核对语义和依据，复用现有参数与结果记录，不要求逐步审批。工具自动拒绝重复/空 ID、缺失样本注释及不可估计的设计；DEG 返回实际两组拟合范围，显式提供 `species`/`id_type` 时附数据库注释。富集区分 ID 映射数与有效注释分母，零显著结果可以正常交付。矩阵重复基因不会再静默求和或择一，需在数据清洗时有依据地处理。
+
+## PyPI 安装与 WorkBuddy 市场包
+
+在 Python 3.11+ 虚拟环境中安装固定版本，获得 PATH 中的 `monadomics` 命令；其参数与 `python3 install.py run` 一致。GitHub 安装不需要这一步。
+
+```bash
+python -m pip install --upgrade monadomics==0.2.3
+monadomics --version
+monadomics doctor --group deg
+```
+
+PyPI 包包含 Python CLI 和 R 分析脚本，不会自动安装 WorkBuddy Skill、R 本体或 Bioconductor 依赖。需要在 WorkBuddy 中使用时，选择上面的 GitHub 安装方式或经审核上架的市场连接器。R 包可在 R 就绪后执行 `monadomics setup-r deg` 安装。
+
+```text
+workbuddy-connector/
+├── connector-meta.json
+├── cli.json
+├── icon.svg
+└── skills/monadomics-analysis/
+    ├── SKILL.md
+    └── references/
+```
+
+`cli.json` 声明 WorkBuddy 托管 Python 3.12，最低 WorkBuddy 5.0.0；macOS/Linux/Windows 都使用固定版本的 pip 安装命令。无登录和 API Key，不配置虚构的 auth/status/unAuth。连接器只声明 CLI，不混入 MCP。
+
+```bash
+python -m pip install build
+python -m build
+python scripts/build_workbuddy_connector.py
+```
+
+生成 Python wheel、sdist，以及 `dist/monadomics-workbuddy-0.2.3.zip`。ZIP 根目录直接包含 connector-meta.json 等文件，符合 [WorkBuddy 连接器规范](https://open.workbuddy.cn/en/docs/connector) 和 [Skill 规范](https://open.workbuddy.cn/en/docs/skill)。
+
+**市场连接器锁定 PyPI 上的 `monadomics==0.2.3`，并需通过 WorkBuddy 审核。** PyPI 发布、本地 wheel 安装和 ZIP 校验均不代表已经在 WorkBuddy 市场上架；当前验证范围见 [RELEASE.md](https://github.com/daisyluvr42/monad_omicskit/blob/main/docs/RELEASE.md)。提交 WorkBuddy 的是连接器 ZIP，Python 包由 init 从 PyPI 安装。GitHub 路线直接部署源码，不依赖该市场初始化命令。
+
+旧 0.1 MCP 代码在 Git 历史中保留。0.2 使用新 Skill `monadomics-analysis`，旧版迁移由上述 GitHub 安装器完成。
+
+## 科学与数据边界
+
+- 原始 count 与标准化/log2 表达必须区分；`normalized` 不代表已采用适当 log2 尺度。DESeq2/edgeR 拒绝非原始 count。
+- 富集需确认物种、ID 类型和背景。GSEA 需要完整排序列表；GSVA/ssGSEA 需要提供来源明确的 `gene_sets`，不会自动下载默认基因集。
+- 基因、通路、P 值、系数不能由模型编造。报告未映射 ID、校正方法和工具警告；富集是关联证据。
+- 生存时间单位、事件编码、候选变量来源须明确。训练集 C-index/AUC 不代表外部验证或临床有效性。
+- 本地计算不上传表达/生存表至另一分析服务器；R 安装、KEGG 等网络功能会访问公共资源。宿主读取的对话和工具输出按 WorkBuddy 自身规则处理。
+
+## 验证
+
+```bash
+python -m pip install -e .
+OMICS_OUTPUT_DIR="$PWD/test-output" python -m unittest discover -s tests -v
+bash tests/smoke_cli.sh
+python tests/run_acceptance.py --output-dir test-output/acceptance
+```
+
+测试数据均为固定种子的合成数据，不是公开患者数据或生物学发现。完整测试需要对应 R 包；缺包时后端测试会明确 skip，不能把 skip 当作分析通过。独立 wheel 验收应使用新环境安装 wheel，从源码目录之外运行 `tests/run_acceptance.py`，并检查生成的表和图。
+
+## 许可证
+
+Copyright 2026 MonadOmics contributors.
+
+MonadOmics 的项目代码、主 Skill 和随附文档采用 [Apache License 2.0](https://github.com/daisyluvr42/monad_omicskit/blob/main/LICENSE)。完整许可证随 Python wheel、源码包和 WorkBuddy 连接器 ZIP 分发；GitHub 安装器也会保留许可证。R、Bioconductor 及其他外部依赖和数据仍遵循各自的许可证。