project-sharing

项目共享与输出准备

为与协作者、评审人员或代码仓库共享项目输出提供专业指导。在保留工作目录的同时，创建不同共享级别的有序打包内容。

此目录中的支持文件：

• notebook-streamlining.md - 精简笔记本以便共享，以及 abridge 选项
• quality-assurance.md - QA 流程、最佳实践、检查清单和依赖管理
• common-scenarios.md - 共享场景（协作者、手稿、归档、代码仓库）和示例脚本
• cleanup-and-deprecation.md - 更正清理错误，以及弃用冗余笔记本

何时使用此技能

• 与协作者共享分析结果
• 为出版物准备补充材料
• 创建可复现的研究包
• 归档已完成的项目
• 向其他研究人员移交项目
• 向数据仓库提交内容

核心原则

1. 在副本上操作 - 切勿修改工作目录
2. 选择合适的级别 - 根据受众需求匹配共享深度
3. 记录所有内容 - 附上清晰的指南和元数据
4. 共享前先清理 - 移除调试代码、清除输出，并在需要时匿名化
5. 确保可复现 - 附上依赖项和说明
6. 重要：创建共享文件夹后，所有后续工作都应在主项目目录中进行，而不是在共享文件夹中进行 - 共享文件夹是只读快照

---

三个共享级别

级别 1：仅摘要

用途： 快速共享，适用于演示、报告或概览评审

包含内容：

• 最终笔记本的 PDF 导出文件
• 最终数据/结果（CSV、Excel、图表）- 可选
• 简短的 README

适用于：

• 与非技术利益相关者共享结果
• 演示或演讲
• 无需复现的快速评审
• 空间/时间受限的情况

结构：

shared-summary/
├── README.md                          # Brief overview
├── analysis-YYYY-MM-DD.pdf           # Notebook as PDF
└── results/
    ├── figures/
    │   ├── fig1-main-result.png
    │   └── fig2-comparison.png
    └── tables/
        └── summary-statistics.csv

---

级别 2：可复现

用途： 让他人能够基于处理后的数据复现分析

包含内容：

• 分析笔记本（.ipynb）- 已清理
• 图表生成脚本
• 已处理/可直接用于分析的数据
• 依赖文件（requirements.txt 或 environment.yml）
• 含详细说明的 README

适用于：

• 与合作研究人员共享
• 同行评审/手稿补充材料
• 教学或教程
• 常规协作需求

结构：

标准项目结构请参阅 folder-organization 技能。可复现的项目包应包含：

• 已处理的数据（位于 data/processed/）
• 已清理的笔记本（位于 notebooks/），并清除输出
• 脚本（位于 scripts/）
• 环境规范文件（environment.yml 或 requirements.txt）
• 文档（README.md、MANIFEST.md）

shared-reproducible/
├── README.md                          # Setup and reproduction instructions
├── MANIFEST.md                        # File descriptions
├── environment.yml                    # Conda environment OR requirements.txt
├── notebooks/                         # Cleaned notebooks
├── scripts/                           # Standalone scripts
└── data/
    └── processed/                     # Analysis-ready data

---

级别 3：完整可追溯性

用途： 从原始数据到所有处理步骤，提供完整透明度

包含内容：

• 起始数据/原始数据
• 所有处理脚本和笔记本
• 所有中间文件
• 最终结果
• 完整文档
• 完整依赖项规范

适用于：

• 归档以供日后参考
• 法规合规
• 高风险领域的可复现性（临床、政策）
• 向数据仓库提交内容（Zenodo、Dryad 等）
• 完整移交项目

结构：

标准项目结构请参阅 folder-organization 技能。完整可追溯项目包应包含完整的数据层级结构：

shared-complete/
├── README.md                          # Complete project guide
├── MANIFEST.md                        # Comprehensive file listing
├── environment.yml
├── data/
│   ├── raw/                          # Original, unmodified data
│   ├── intermediate/                 # Processing steps
│   └── processed/                    # Final analysis-ready
├── scripts/                           # All processing scripts
├── notebooks/                         # All notebooks (exploratory + final)
├── results/                           # All outputs
│   ├── figures/
│   ├── tables/
│   └── supplementary/
└── documentation/                     # Complete documentation
    ├── methods.md
    ├── changelog.md
    └── data-dictionary.md

---

准备工作流

步骤 1：询问用户共享级别

用于确定级别的问题：

Which sharing level do you need?

1. Summary Only - PDF + final results (quick sharing)
2. Reproducible - Notebooks + scripts + data (standard sharing)
3. Full Traceability - Everything from raw data (archival/compliance)

Additional questions:
- Who is the audience? (colleagues, reviewers, public)
- Are there size constraints?
- Any sensitive data to handle?
- Timeline for sharing?

第 2 步：确定要包含的文件

级别 1 - 摘要：

• 主要分析笔记本
• 关键图表（达到发表质量）
• 摘要表格/统计数据

级别 2 - 可复现：

• 所有分析笔记本（不包括探索性笔记本）
• 图表生成脚本
• 处理后/清理后的数据
• 环境规范
• 所有实用函数/模块

级别 3 - 完整：

• 原始数据（或数据过大时提供链接）
• 所有处理脚本
• 所有笔记本（包括探索性笔记本）
• 所有中间文件
• 完整文档

第 3 步：创建共享目录

# Create dated directory
SHARE_DIR="shared-$(date +%Y%m%d)-[level]"
mkdir -p "$SHARE_DIR"

第 4 步：复制并清理文件

对于笔记本（.ipynb）：

import nbformat
from nbconvert.preprocessors import ClearOutputPreprocessor

def clean_notebook(input_path, output_path):
    """Clean notebook: clear outputs, remove debug cells."""
    with open(input_path, 'r') as f:
        nb = nbformat.read(f, as_version=4)

    clear_output = ClearOutputPreprocessor()
    nb, _ = clear_output.preprocess(nb, {})

    nb.cells = [cell for cell in nb.cells
                if 'debug' not in cell.metadata.get('tags', [])
                and 'remove' not in cell.metadata.get('tags', [])]

    with open(output_path, 'w') as f:
        nbformat.write(nb, f)

**对于数据文件：**小文件原样复制；大文件压缩；检查是否包含敏感信息。

**对于脚本：**删除调试代码；缺少文档字符串时补上；确保路径为相对路径。

有关笔记本精简和 abridge 选项，请参阅 notebook-streamlining.md。

第 4.5 步：验证并修正文件路径

问题：笔记本和脚本中的文件路径失效时，共享后将无法正常运行。

有关完整的路径验证流程、自动检查脚本和修正模式，请参阅 folder-organization 技能。

共享后会失效	共享后可正常使用
/Users/yourname/project/data.csv	data/data.csv
C:\Users\yourname\project\fig.png	figures/fig.png
/absolute/path/to/results/	results/

快速检查命令：

# Check for absolute paths in notebooks
grep -l "/Users/" *.ipynb
grep -l "C:\\\\" *.ipynb

第 5 步：生成文档

README.md 模板

# Project: [Project Name]

**Date:** YYYY-MM-DD
**Author:** [Your Name]
**Sharing Level:** [Summary/Reproducible/Full]

## Overview
Brief description of the project and analysis.

## Contents
See MANIFEST.md for detailed file descriptions.

## Requirements
[For Reproducible/Full levels]
- Python 3.X
- See environment.yml for dependencies

## Setup
\`\`\`bash
conda env create -f environment.yml
conda activate project-name
\`\`\`

## Reproduction Steps
[For Reproducible/Full levels]
1. [Description of first step]

## Data Sources
[For Full level]
- Dataset A: [Source, download date, version]

## Contact
[Your email or preferred contact]

## License
[If applicable - e.g., CC BY 4.0, MIT]

MANIFEST.md 模板

# File Manifest
Generated: YYYY-MM-DD

## File Descriptions

### Notebooks
- \`notebooks/01-data-processing.ipynb\` - Initial data loading and cleaning
- \`notebooks/02-analysis.ipynb\` - Main statistical analysis

### Data
- \`data/processed/cleaned_data.csv\` - Quality-controlled dataset (N=XXX samples)

### Scripts
- \`scripts/generate_figures.py\` - Automated figure generation

### Results
- \`results/figures/fig1-main.png\` - Main result showing [description]

第 6 步：处理敏感数据

**检查以下内容：**个人身份信息（PII）、访问凭据、专有数据、机构限制、患者/受试者标识符。

处理策略：

1. 匿名化 - 删除或哈希处理标识符
2. 排除 - 不包含敏感文件
3. 汇总 - 仅共享摘要统计数据
4. 记录限制 - 注明排除了哪些内容及原因

第 7 步：打包并压缩

# For smaller packages (<100MB)
zip -r shared-YYYYMMDD.zip shared-YYYYMMDD/

# For larger packages
tar -czf shared-YYYYMMDD.tar.gz shared-YYYYMMDD/

第 8 步：返回工作目录

重要：创建共享包后，务必在主项目目录中工作。

共享文件夹只是用于分发的快照。今后的所有开发、分析或修改都应在原始工作目录中进行。

cd /path/to/main/project  # Return to working directory
pwd                        # Verify location
# Continue work here, NOT in shared-YYYYMMDD/

---

与其他技能集成

适配良好：

• folder-organization - 确保共享前源项目已妥善整理
• jupyter-notebook-analysis - 创建可直接共享的笔记本
• managing-environments - 妥善记录依赖项

使用此技能前：

1. 整理工作目录（folder-organization）
2. 完成分析（jupyter-notebook-analysis）
3. 记录环境信息（managing-environments）

使用此技能后：

1. 在干净的环境中测试软件包
2. 通过合适的渠道共享（电子邮件、代码仓库、云存储）
3. 保留归档副本以供参考

有关质量保证流程和检查清单，请参阅 quality-assurance.md。 有关常见共享场景和示例脚本，请参阅 common-scenarios.md。 有关处理清理错误和弃用笔记本，请参阅 cleanup-and-deprecation.md。

---

总结

项目共享的关键原则：

1. 选择合适的级别 - 根据受众需求确定共享深度
2. 复制而非移动 - 保留工作目录
3. 彻底清理 - 删除调试代码，清除输出
4. 完整记录 - 至少提供 README + MANIFEST
5. 检查敏感信息 - 按需匿名化或排除
6. 共享前测试 - 在干净的环境中运行
7. 妥善打包 - 压缩并记录内容
8. 在主目录中工作 - 创建共享包后，今后的所有工作都应在原始项目目录中进行，而非共享文件夹

**请记住：**良好的共享实践有益于合作者，也有益于未来的自己！

---

给 Claude 的重要提醒

创建任何共享包后：

1. 始终返回主项目目录
2. 切勿在 shared-*/ 目录中工作——这些是只读快照
3. 之后的所有编辑、分析和开发都在原始工作目录中进行
4. 共享文件夹仅用于分发，不用于实际开发

如果用户要求修改文件，务必检查当前目录，并确认你是在主项目位置而非共享包中工作。